Unverified Commit 872c8d5c authored by Shu Ding's avatar Shu Ding Committed by GitHub

Show link to the docs for route segment config options (#42779)

This PR adds links to the docs when hovering on the option names and
values. It will be helpful especially when there's an invalid value:


![option-links](https://user-images.githubusercontent.com/3676859/201303933-8a8bcfd3-4e6b-4191-a0b0-2944539ccf66.gif)

## Bug

- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Errors have a helpful link attached, see `contributing.md`

## Feature

- [ ] Implements an existing feature request or RFC. Make sure the
feature request has been accepted for implementation before opening a
PR.
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have a helpful link attached, see `contributing.md`

## Documentation / Examples

- [ ] Make sure the linting passes by running `pnpm build && pnpm lint`
- [ ] The "examples guidelines" are followed from [our contributing
doc](https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md)
parent 4240dcc4
...@@ -41,6 +41,7 @@ const API_DOCS: Record< ...@@ -41,6 +41,7 @@ const API_DOCS: Record<
{ {
description: string description: string
options: Record<string, string> options: Record<string, string>
link: string
type?: string type?: string
isValid?: (value: string) => boolean isValid?: (value: string) => boolean
getHint?: (value: any) => string getHint?: (value: any) => string
...@@ -59,6 +60,7 @@ const API_DOCS: Record< ...@@ -59,6 +60,7 @@ const API_DOCS: Record<
'"force-static"': '"force-static"':
'This forces caching of all fetches and returns empty values from `useCookies`, `useHeaders` and `useSearchParams`.', 'This forces caching of all fetches and returns empty values from `useCookies`, `useHeaders` and `useSearchParams`.',
}, },
link: 'https://beta.nextjs.org/docs/api-reference/segment-config#dynamic',
}, },
fetchCache: { fetchCache: {
description: description:
...@@ -79,6 +81,7 @@ const API_DOCS: Record< ...@@ -79,6 +81,7 @@ const API_DOCS: Record<
'"force-cache"': '"force-cache"':
"This lets you intentionally opt-in to all caching of data. This option forces all fetches to be cache even if the `cache: 'no-store'` option is passed to `fetch()`.", "This lets you intentionally opt-in to all caching of data. This option forces all fetches to be cache even if the `cache: 'no-store'` option is passed to `fetch()`.",
}, },
link: 'https://beta.nextjs.org/docs/api-reference/segment-config#fetchcache',
}, },
preferredRegion: { preferredRegion: {
description: description:
...@@ -89,6 +92,7 @@ const API_DOCS: Record< ...@@ -89,6 +92,7 @@ const API_DOCS: Record<
'"home"': 'Prefer deploying to the Home region.', '"home"': 'Prefer deploying to the Home region.',
'"edge"': 'Prefer deploying to the Edge globally.', '"edge"': 'Prefer deploying to the Edge globally.',
}, },
link: 'https://beta.nextjs.org/docs/api-reference/segment-config#preferredregion',
}, },
revalidate: { revalidate: {
description: description:
...@@ -100,6 +104,7 @@ const API_DOCS: Record< ...@@ -100,6 +104,7 @@ const API_DOCS: Record<
0: 'Specifying `0` implies that this layout or page should never be static.', 0: 'Specifying `0` implies that this layout or page should never be static.',
30: 'Set the revalidation time to `30` seconds. The value can be `0` or any positive number.', 30: 'Set the revalidation time to `30` seconds. The value can be `0` or any positive number.',
}, },
link: 'https://beta.nextjs.org/docs/api-reference/segment-config#revalidate',
isValid: (value: string) => { isValid: (value: string) => {
return value === 'false' || Number(value) >= 0 return value === 'false' || Number(value) >= 0
}, },
...@@ -115,6 +120,7 @@ const API_DOCS: Record< ...@@ -115,6 +120,7 @@ const API_DOCS: Record<
false: false:
'Disallow rendering dynamic params that are not generated by `generateStaticParams`.', 'Disallow rendering dynamic params that are not generated by `generateStaticParams`.',
}, },
link: 'https://beta.nextjs.org/docs/api-reference/segment-config#dynamicparams',
}, },
runtime: { runtime: {
description: description:
...@@ -123,6 +129,7 @@ const API_DOCS: Record< ...@@ -123,6 +129,7 @@ const API_DOCS: Record<
'"nodejs"': 'Prefer the Node.js runtime.', '"nodejs"': 'Prefer the Node.js runtime.',
'"experimental-edge"': 'Prefer the experimental Edge runtime.', '"experimental-edge"': 'Prefer the experimental Edge runtime.',
}, },
link: 'https://beta.nextjs.org/docs/api-reference/segment-config#runtime',
}, },
} }
...@@ -217,8 +224,7 @@ export function createTSPlugin(modules: { ...@@ -217,8 +224,7 @@ export function createTSPlugin(modules: {
messageText: messageText:
'The `"use client"` directive must be put at the top of the file.', 'The `"use client"` directive must be put at the top of the file.',
start: node.expression.getStart(), start: node.expression.getStart(),
length: length: node.expression.getWidth(),
node.expression.getEnd() - node.expression.getStart(),
} }
throw e throw e
} }
...@@ -428,6 +434,13 @@ export function createTSPlugin(modules: { ...@@ -428,6 +434,13 @@ export function createTSPlugin(modules: {
const name = declarartion.name const name = declarartion.name
const value = declarartion.initializer const value = declarartion.initializer
const docsLink = {
kind: 'text',
text:
`\n\nRead more about the "${entryConfig}" option: ` +
API_DOCS[entryConfig].link,
}
if ( if (
value && value &&
value.getFullStart() <= position && value.getFullStart() <= position &&
...@@ -459,28 +472,41 @@ export function createTSPlugin(modules: { ...@@ -459,28 +472,41 @@ export function createTSPlugin(modules: {
API_DOCS[entryConfig].getHint?.(key) || API_DOCS[entryConfig].getHint?.(key) ||
'', '',
}, },
docsLink,
], ],
} }
} } else {
} else { // Wrong value, display the docs link
// Hovers the name of the config
if (API_DOCS[entryConfig]) {
overriden = { overriden = {
kind: ts.ScriptElementKind.enumElement, kind: ts.ScriptElementKind.enumElement,
kindModifiers: ts.ScriptElementKindModifier.none, kindModifiers: ts.ScriptElementKindModifier.none,
textSpan: { textSpan: {
start: name.getStart(), start: value.getStart(),
length: name.getWidth(), length: value.getWidth(),
}, },
displayParts: [], displayParts: [],
documentation: [ documentation: [docsLink],
{
kind: 'text',
text: getAPIDescription(entryConfig),
},
],
} }
} }
} else {
// Hovers the name of the config
overriden = {
kind: ts.ScriptElementKind.enumElement,
kindModifiers: ts.ScriptElementKindModifier.none,
textSpan: {
start: name.getStart(),
length: name.getWidth(),
},
displayParts: [],
documentation: [
{
kind: 'text',
text: getAPIDescription(entryConfig),
},
docsLink,
],
}
} }
}) })
if (overriden) return overriden if (overriden) return overriden
...@@ -529,8 +555,7 @@ export function createTSPlugin(modules: { ...@@ -529,8 +555,7 @@ export function createTSPlugin(modules: {
code: NEXT_TS_ERRORS.INVALID_SERVER_API, code: NEXT_TS_ERRORS.INVALID_SERVER_API,
messageText: `"${name}" is not allowed in Server Components.`, messageText: `"${name}" is not allowed in Server Components.`,
start: element.name.getStart(), start: element.name.getStart(),
length: length: element.name.getWidth(),
element.name.getEnd() - element.name.getStart(),
}) })
} }
} }
...@@ -556,7 +581,7 @@ export function createTSPlugin(modules: { ...@@ -556,7 +581,7 @@ export function createTSPlugin(modules: {
code: NEXT_TS_ERRORS.INVALID_ENTRY_EXPORT, code: NEXT_TS_ERRORS.INVALID_ENTRY_EXPORT,
messageText: `"${name.text}" is not a valid Next.js entry export value.`, messageText: `"${name.text}" is not a valid Next.js entry export value.`,
start: name.getStart(), start: name.getStart(),
length: name.getEnd() - name.getStart(), length: name.getWidth(),
}) })
} else if (API_DOCS[name.text]) { } else if (API_DOCS[name.text]) {
// Check if the value is valid // Check if the value is valid
...@@ -612,7 +637,8 @@ export function createTSPlugin(modules: { ...@@ -612,7 +637,8 @@ export function createTSPlugin(modules: {
ts.isBigIntLiteral(value) || ts.isBigIntLiteral(value) ||
ts.isArrayLiteralExpression(value) || ts.isArrayLiteralExpression(value) ||
ts.isObjectLiteralExpression(value) || ts.isObjectLiteralExpression(value) ||
ts.isRegularExpressionLiteral(value) ts.isRegularExpressionLiteral(value) ||
ts.isPrefixUnaryExpression(value)
) { ) {
isInvalid = true isInvalid = true
displayedValue = value.getText() displayedValue = value.getText()
...@@ -632,7 +658,7 @@ export function createTSPlugin(modules: { ...@@ -632,7 +658,7 @@ export function createTSPlugin(modules: {
errorMessage || errorMessage ||
`"${displayedValue}" is not a valid value for the "${name.text}" option.`, `"${displayedValue}" is not a valid value for the "${name.text}" option.`,
start: value.getStart(), start: value.getStart(),
length: value.getEnd() - value.getStart(), length: value.getWidth(),
}) })
} }
} }
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment