Unverified Commit 77aa75c6 authored by Shu Ding's avatar Shu Ding Committed by GitHub

Improve TS experience for metadata (#45493)

This PR adds the corresponding TS plugin logic for the `metadata` export
field. In short, it provides the same IntelliSense experience to that
export value even if it isn't typed manually with `Metadata`. It is
implemented via an in-memory TypeScript LanguageServiceHost, that
attaches the `Metadata` type to the original node (if it's not typed by
the user) and handles the actual IntelliSense requests. Our plugin here
only services as a proxy.

That said, in our docs (and even in our JSDoc of metadata), we should
still recommend people to type it manually.

Also note that `generateMetadata` isn't enhanced with this yet.

## Bug

- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Errors have a helpful link attached, see
[`contributing.md`](https://github.com/vercel/next.js/blob/canary/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`
- [ ]
[e2e](https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
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`](https://github.com/vercel/next.js/blob/canary/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 97796586
...@@ -181,6 +181,7 @@ export class FlightTypesPlugin { ...@@ -181,6 +181,7 @@ export class FlightTypesPlugin {
} }
} }
await Promise.all(promises) await Promise.all(promises)
callback() callback()
} }
) )
......
...@@ -64,6 +64,21 @@ export interface Metadata { ...@@ -64,6 +64,21 @@ export interface Metadata {
// to get more specific about rel types // to get more specific about rel types
icons?: null | IconURL | Array<Icon> | Icons icons?: null | IconURL | Array<Icon> | Icons
/**
* @example
* Example of Open Graph field:
* ```
* {
* type: "website",
* url: "https://example.com",
* siteName: "My Website",
* title: "My Website",
* images: [{
* url: "https://example.com/og.png",
* }],
* }
* ```
*/
openGraph?: null | OpenGraph openGraph?: null | OpenGraph
twitter?: null | Twitter twitter?: null | Twitter
......
...@@ -22,6 +22,7 @@ import entryConfig from './rules/config' ...@@ -22,6 +22,7 @@ import entryConfig from './rules/config'
import serverLayer from './rules/server' import serverLayer from './rules/server'
import entryDefault from './rules/entry' import entryDefault from './rules/entry'
import clientBoundary from './rules/client-boundary' import clientBoundary from './rules/client-boundary'
import metadata from './rules/metadata'
export function createTSPlugin(modules: { export function createTSPlugin(modules: {
typescript: typeof import('typescript/lib/tsserverlibrary') typescript: typeof import('typescript/lib/tsserverlibrary')
...@@ -59,14 +60,22 @@ export function createTSPlugin(modules: { ...@@ -59,14 +60,22 @@ export function createTSPlugin(modules: {
} }
if (!isAppEntryFile(fileName)) return prior if (!isAppEntryFile(fileName)) return prior
// Remove specified entries from completion list if it's a server entry. // If it's a server entry.
if (!getIsClientEntry(fileName)) { if (!getIsClientEntry(fileName)) {
// Remove specified entries from completion list
prior.entries = serverLayer.filterCompletionsAtPosition(prior.entries) prior.entries = serverLayer.filterCompletionsAtPosition(prior.entries)
// Provide autocompletion for metadata fields
prior = metadata.filterCompletionsAtPosition(
fileName,
position,
options,
prior
)
} }
// Add auto completions for export configs. // Add auto completions for export configs.
const entries = entryConfig.getCompletionsAtPosition(fileName, position) entryConfig.addCompletionsAtPosition(fileName, position, prior)
prior.entries = [...prior.entries, ...entries]
const source = getSource(fileName) const source = getSource(fileName)
if (!source) return prior if (!source) return prior
...@@ -106,6 +115,17 @@ export function createTSPlugin(modules: { ...@@ -106,6 +115,17 @@ export function createTSPlugin(modules: {
) )
if (entryCompletionEntryDetails) return entryCompletionEntryDetails if (entryCompletionEntryDetails) return entryCompletionEntryDetails
const metadataCompletionEntryDetails = metadata.getCompletionEntryDetails(
fileName,
position,
entryName,
formatOptions,
source,
preferences,
data
)
if (metadataCompletionEntryDetails) return metadataCompletionEntryDetails
return info.languageService.getCompletionEntryDetails( return info.languageService.getCompletionEntryDetails(
fileName, fileName,
position, position,
...@@ -137,6 +157,9 @@ export function createTSPlugin(modules: { ...@@ -137,6 +157,9 @@ export function createTSPlugin(modules: {
) { ) {
return return
} }
const metadataInfo = metadata.getQuickInfoAtPosition(fileName, position)
if (metadataInfo) return metadataInfo
} }
const overriden = entryConfig.getQuickInfoAtPosition(fileName, position) const overriden = entryConfig.getQuickInfoAtPosition(fileName, position)
...@@ -191,7 +214,12 @@ export function createTSPlugin(modules: { ...@@ -191,7 +214,12 @@ export function createTSPlugin(modules: {
source, source,
node node
) )
prior.push(...diagnostics) const metadataDiagnostics =
metadata.getSemanticDiagnosticsForExportVariableStatement(
fileName,
node
)
prior.push(...diagnostics, ...metadataDiagnostics)
} }
if (isClientEntry) { if (isClientEntry) {
......
...@@ -16,8 +16,8 @@ const API_DOCS: Record< ...@@ -16,8 +16,8 @@ const API_DOCS: Record<
string, string,
{ {
description: string description: string
options: Record<string, string> options?: Record<string, string>
link: string link?: string
type?: string type?: string
isValid?: (value: string) => boolean isValid?: (value: string) => boolean
getHint?: (value: any) => string getHint?: (value: any) => string
...@@ -108,6 +108,10 @@ const API_DOCS: Record< ...@@ -108,6 +108,10 @@ const API_DOCS: Record<
}, },
link: 'https://beta.nextjs.org/docs/api-reference/segment-config#runtime', link: 'https://beta.nextjs.org/docs/api-reference/segment-config#runtime',
}, },
metadata: {
description: 'Next.js Metadata configurations',
link: 'https://beta.nextjs.org/docs/',
},
} }
function visitEntryConfig( function visitEntryConfig(
...@@ -128,11 +132,7 @@ function visitEntryConfig( ...@@ -128,11 +132,7 @@ function visitEntryConfig(
) { ) {
if (ts.isVariableDeclarationList(node.declarationList)) { if (ts.isVariableDeclarationList(node.declarationList)) {
for (const declaration of node.declarationList.declarations) { for (const declaration of node.declarationList.declarations) {
if ( if (isPositionInsideNode(position, declaration)) {
declaration.getFullStart() <= position &&
position <=
declaration.getFullStart() + declaration.getFullWidth()
) {
// `export const ... = ...` // `export const ... = ...`
const text = declaration.name.getText() const text = declaration.name.getText()
callback(text, declaration) callback(text, declaration)
...@@ -149,8 +149,8 @@ function createAutoCompletionOptionName(sort: number, name: string) { ...@@ -149,8 +149,8 @@ function createAutoCompletionOptionName(sort: number, name: string) {
const ts = getTs() const ts = getTs()
return { return {
name, name,
sortText: '' + sort, sortText: '!' + sort,
kind: ts.ScriptElementKind.unknown, kind: ts.ScriptElementKind.constElement,
kindModifiers: ts.ScriptElementKindModifier.exportedModifier, kindModifiers: ts.ScriptElementKindModifier.exportedModifier,
labelDetails: { labelDetails: {
description: `Next.js ${name} option`, description: `Next.js ${name} option`,
...@@ -189,24 +189,22 @@ function getAPIDescription(api: string): string { ...@@ -189,24 +189,22 @@ function getAPIDescription(api: string): string {
return ( return (
API_DOCS[api].description + API_DOCS[api].description +
'\n\n' + '\n\n' +
Object.entries(API_DOCS[api].options) Object.entries(API_DOCS[api].options || {})
.map(([key, value]) => `- \`${key}\`: ${value}`) .map(([key, value]) => `- \`${key}\`: ${value}`)
.join('\n') .join('\n')
) )
} }
const config = { const config = {
// Auto completion for entry exported configs. // Auto completion for entry exported configs.
getCompletionsAtPosition(fileName: string, position: number) { addCompletionsAtPosition(
const entries: ts.CompletionEntry[] = [] fileName: string,
position: number,
prior: ts.WithMetadata<ts.CompletionInfo>
) {
visitEntryConfig(fileName, position, (entryConfig, declaration) => { visitEntryConfig(fileName, position, (entryConfig, declaration) => {
if (!API_DOCS[entryConfig]) { if (!API_DOCS[entryConfig]) {
if ( if (isPositionInsideNode(position, declaration.name)) {
declaration.name.getFullStart() <= position && prior.entries.push(
position <=
declaration.name.getFullStart() + declaration.name.getFullWidth()
) {
entries.push(
...Object.keys(API_DOCS).map((name, index) => { ...Object.keys(API_DOCS).map((name, index) => {
return createAutoCompletionOptionName(index, name) return createAutoCompletionOptionName(index, name)
}) })
...@@ -215,14 +213,14 @@ const config = { ...@@ -215,14 +213,14 @@ const config = {
return return
} }
entries.push( prior.entries.push(
...Object.keys(API_DOCS[entryConfig].options).map((name, index) => { ...Object.keys(API_DOCS[entryConfig].options || {}).map(
return createAutoCompletionOptionValue(index, name, entryConfig) (name, index) => {
}) return createAutoCompletionOptionValue(index, name, entryConfig)
}
)
) )
}) })
return entries
}, },
// Show docs when hovering on the exported configs. // Show docs when hovering on the exported configs.
...@@ -243,11 +241,7 @@ const config = { ...@@ -243,11 +241,7 @@ const config = {
API_DOCS[entryConfig].link, API_DOCS[entryConfig].link,
} }
if ( if (value && isPositionInsideNode(position, value)) {
value &&
value.getFullStart() <= position &&
value.getFullStart() + value.getFullWidth() >= position
) {
// Hovers the value of the config // Hovers the value of the config
const isString = ts.isStringLiteral(value) const isString = ts.isStringLiteral(value)
const text = removeStringQuotes(value.getText()) const text = removeStringQuotes(value.getText())
...@@ -255,7 +249,7 @@ const config = { ...@@ -255,7 +249,7 @@ const config = {
const isValid = API_DOCS[entryConfig].isValid const isValid = API_DOCS[entryConfig].isValid
? API_DOCS[entryConfig].isValid?.(key) ? API_DOCS[entryConfig].isValid?.(key)
: !!API_DOCS[entryConfig].options[key] : !!API_DOCS[entryConfig].options?.[key]
if (isValid) { if (isValid) {
overriden = { overriden = {
...@@ -270,7 +264,7 @@ const config = { ...@@ -270,7 +264,7 @@ const config = {
{ {
kind: 'text', kind: 'text',
text: text:
API_DOCS[entryConfig].options[key] || API_DOCS[entryConfig].options?.[key] ||
API_DOCS[entryConfig].getHint?.(key) || API_DOCS[entryConfig].getHint?.(key) ||
'', '',
}, },
...@@ -325,7 +319,9 @@ const config = { ...@@ -325,7 +319,9 @@ const config = {
if (data.moduleSpecifier === 'next/typescript/entry_option_name') { if (data.moduleSpecifier === 'next/typescript/entry_option_name') {
content = getAPIDescription(entryName) content = getAPIDescription(entryName)
} else { } else {
content = API_DOCS[data.exportName].options[entryName] const options = API_DOCS[data.exportName].options
if (!options) return
content = options[entryName]
} }
return { return {
name: entryName, name: entryName,
...@@ -368,8 +364,9 @@ const config = { ...@@ -368,8 +364,9 @@ const config = {
} else if (API_DOCS[name.text]) { } else if (API_DOCS[name.text]) {
// Check if the value is valid // Check if the value is valid
const value = declaration.initializer const value = declaration.initializer
const options = API_DOCS[name.text].options
if (value) { if (value && options) {
let displayedValue = '' let displayedValue = ''
let errorMessage = '' let errorMessage = ''
let isInvalid = false let isInvalid = false
...@@ -379,7 +376,7 @@ const config = { ...@@ -379,7 +376,7 @@ const config = {
ts.isNoSubstitutionTemplateLiteral(value) ts.isNoSubstitutionTemplateLiteral(value)
) { ) {
const text = removeStringQuotes(value.getText()) const text = removeStringQuotes(value.getText())
const allowedValues = Object.keys(API_DOCS[name.text].options) const allowedValues = Object.keys(options)
.filter((v) => /^['"]/.test(v)) .filter((v) => /^['"]/.test(v))
.map(removeStringQuotes) .map(removeStringQuotes)
......
import { getInfo, getSource, getTs, isPositionInsideNode } from '../utils'
const TYPE_ANOTATION = ': Metadata'
const TYPE_IMPORT = `import type { Metadata } from 'next'`
// Find the `export const metadata = ...` node.
function getMetadataExport(fileName: string, position: number) {
const source = getSource(fileName)
let metadataExport: ts.VariableDeclaration | undefined
if (source) {
const ts = getTs()
ts.forEachChild(source, function visit(node) {
if (metadataExport) return
// Covered by this node
if (isPositionInsideNode(position, node)) {
// Export variable
if (
ts.isVariableStatement(node) &&
node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
) {
if (ts.isVariableDeclarationList(node.declarationList)) {
for (const declaration of node.declarationList.declarations) {
if (
isPositionInsideNode(position, declaration) &&
declaration.name.getText() === 'metadata'
) {
// `export const metadata = ...`
metadataExport = declaration
return
}
}
}
}
}
})
}
return metadataExport
}
let cachedProxiedLanguageService: ts.LanguageService | undefined
let cachedProxiedLanguageServiceHost: ts.LanguageServiceHost | undefined
function getProxiedLanguageService() {
if (cachedProxiedLanguageService)
return {
languageService: cachedProxiedLanguageService as ts.LanguageService,
languageServiceHost:
cachedProxiedLanguageServiceHost as ts.LanguageServiceHost & {
addFile: (fileName: string, body: string) => void
},
}
const languageServiceHost = getInfo().languageServiceHost
const ts = getTs()
class ProxiedLanguageServiceHost implements ts.LanguageServiceHost {
files: { [fileName: string]: { file: ts.IScriptSnapshot; ver: number } } =
{}
log = () => {}
trace = () => {}
error = () => {}
getCompilationSettings = () => languageServiceHost.getCompilationSettings()
getScriptIsOpen = () => true
getCurrentDirectory = () => languageServiceHost.getCurrentDirectory()
getDefaultLibFileName = (o: any) =>
languageServiceHost.getDefaultLibFileName(o)
getScriptVersion = (fileName: string) => {
const file = this.files[fileName]
if (!file) return languageServiceHost.getScriptVersion(fileName)
return file.ver.toString()
}
getScriptSnapshot = (fileName: string) => {
const file = this.files[fileName]
if (!file) return languageServiceHost.getScriptSnapshot(fileName)
return file.file
}
getScriptFileNames(): string[] {
const names: Set<string> = new Set()
for (var name in this.files) {
if (this.files.hasOwnProperty(name)) {
names.add(name)
}
}
const files = languageServiceHost.getScriptFileNames()
for (const file of files) {
names.add(file)
}
return [...names]
}
addFile(fileName: string, body: string) {
const snap = ts.ScriptSnapshot.fromString(body)
snap.getChangeRange = (_) => undefined
const existing = this.files[fileName]
if (existing) {
this.files[fileName].ver++
this.files[fileName].file = snap
} else {
this.files[fileName] = { ver: 1, file: snap }
}
}
readFile(fileName: string) {
const file = this.files[fileName]
return file
? file.file.getText(0, file.file.getLength())
: languageServiceHost.readFile(fileName)
}
fileExists(fileName: string) {
return (
this.files[fileName] !== undefined ||
languageServiceHost.fileExists(fileName)
)
}
}
cachedProxiedLanguageServiceHost = new ProxiedLanguageServiceHost()
cachedProxiedLanguageService = ts.createLanguageService(
cachedProxiedLanguageServiceHost,
ts.createDocumentRegistry()
)
return {
languageService: cachedProxiedLanguageService as ts.LanguageService,
languageServiceHost:
cachedProxiedLanguageServiceHost as ts.LanguageServiceHost & {
addFile: (fileName: string, body: string) => void
},
}
}
function updateVirtualFileWithType(
fileName: string,
node: ts.VariableDeclaration
) {
const source = getSource(fileName)
if (!source) return
// We annotate with the type in a vritual language service
const sourceText = source.getFullText()
const nodeEnd = node.name.getFullStart() + node.name.getFullWidth()
const newSource =
sourceText.slice(0, nodeEnd) +
TYPE_ANOTATION +
sourceText.slice(nodeEnd) +
TYPE_IMPORT
const { languageServiceHost } = getProxiedLanguageService()
languageServiceHost.addFile(fileName, newSource)
return nodeEnd
}
function isTyped(node: ts.VariableDeclaration) {
return node.type !== undefined
}
const metadata = {
filterCompletionsAtPosition(
fileName: string,
position: number,
_options: any,
prior: ts.WithMetadata<ts.CompletionInfo>
) {
const node = getMetadataExport(fileName, position)
if (!node) return prior
if (isTyped(node)) return prior
const ts = getTs()
// We annotate with the type in a vritual language service
const nodeEnd = updateVirtualFileWithType(fileName, node)
if (nodeEnd === undefined) return prior
// Get completions
const { languageService } = getProxiedLanguageService()
const newPos =
position <= nodeEnd ? position : position + TYPE_ANOTATION.length
const completions = languageService.getCompletionsAtPosition(
fileName,
newPos,
undefined
)
if (completions) {
completions.isIncomplete = true
completions.entries = completions.entries
.filter((e) => {
return [
ts.ScriptElementKind.memberVariableElement,
ts.ScriptElementKind.typeElement,
ts.ScriptElementKind.string,
].includes(e.kind)
})
.map((e) => {
const insertText =
e.kind === ts.ScriptElementKind.memberVariableElement &&
/^[a-zA-Z0-9_]+$/.test(e.name)
? e.name + ': '
: e.name
return {
name: e.name,
insertText,
kind: e.kind,
kindModifiers: e.kindModifiers,
sortText: '!' + e.name,
labelDetails: {
description: `Next.js metadata`,
},
data: e.data,
}
})
return completions
}
return prior
},
getSemanticDiagnosticsForExportVariableStatement(
fileName: string,
node: ts.VariableStatement
) {
const source = getSource(fileName)
for (const declaration of node.declarationList.declarations) {
if (declaration.name.getText() === 'metadata') {
if (isTyped(declaration)) break
// We annotate with the type in a vritual language service
const nodeEnd = updateVirtualFileWithType(fileName, declaration)
if (!nodeEnd) break
// Get diagnostics
const { languageService } = getProxiedLanguageService()
const diagnostics = languageService.getSemanticDiagnostics(fileName)
// Filter and map the results
return diagnostics
.filter((d) => {
if (d.start === undefined || d.length === undefined) return false
if (d.start < declaration.getFullStart()) return false
if (
d.start + d.length >
declaration.getFullStart() +
declaration.getFullWidth() +
TYPE_ANOTATION.length
)
return false
return true
})
.map((d) => {
return {
file: source,
category: d.category,
code: d.code,
messageText: d.messageText,
start:
d.start! <= nodeEnd
? d.start
: d.start! - TYPE_ANOTATION.length,
length: d.length,
}
})
}
}
return []
},
getCompletionEntryDetails(
fileName: string,
position: number,
entryName: string,
formatOptions: ts.FormatCodeOptions,
source: string,
preferences: ts.UserPreferences,
data: ts.CompletionEntryData
) {
const node = getMetadataExport(fileName, position)
if (!node) return
if (isTyped(node)) return
// We annotate with the type in a vritual language service
const nodeEnd = updateVirtualFileWithType(fileName, node)
if (nodeEnd === undefined) return
const { languageService } = getProxiedLanguageService()
const newPos =
position <= nodeEnd ? position : position + TYPE_ANOTATION.length
const details = languageService.getCompletionEntryDetails(
fileName,
newPos,
entryName,
formatOptions,
source,
preferences,
data
)
return details
},
getQuickInfoAtPosition(fileName: string, position: number) {
const node = getMetadataExport(fileName, position)
if (!node) return
if (isTyped(node)) return
// We annotate with the type in a vritual language service
const nodeEnd = updateVirtualFileWithType(fileName, node)
if (nodeEnd === undefined) return
const { languageService } = getProxiedLanguageService()
const newPos =
position <= nodeEnd ? position : position + TYPE_ANOTATION.length
const insight = languageService.getQuickInfoAtPosition(fileName, newPos)
return insight
},
}
export default metadata
...@@ -28,6 +28,10 @@ export function getTs() { ...@@ -28,6 +28,10 @@ export function getTs() {
return ts return ts
} }
export function getInfo() {
return info
}
export function getTypeChecker() { export function getTypeChecker() {
return info.languageService.getProgram()?.getTypeChecker() return info.languageService.getProgram()?.getTypeChecker()
} }
...@@ -88,7 +92,7 @@ export function getIsClientEntry( ...@@ -88,7 +92,7 @@ export function getIsClientEntry(
fileName: string, fileName: string,
throwOnInvalidDirective?: boolean throwOnInvalidDirective?: boolean
) { ) {
const source = info.languageService.getProgram()?.getSourceFile(fileName) const source = getSource(fileName)
if (source) { if (source) {
let isClientEntry = false let isClientEntry = false
let isDirective = true let isDirective = true
......
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