address completions and extract utils

Author: dimitropoulos

packages/next/src/server/next.ts

@@ -461,8 +461,17 @@ function createServer(
     process.env.TURBOPACK = '1'
   }
 
-  // The package is used as a TypeScript plugin.
-  if (options && 'typescript' in options && 'version' in (options as any).typescript) {
+  // The `next` package can be used as a TypeScript language server plugin.
+  // This is a special case where we don't want to start the server.
+  // That's why although the `options` values are technically valid,
+  // we keep them out of the public types for `createServer` to avoid confusion.
+  if (
+    options &&
+    'typescript' in options &&
+    options.typescript &&
+    typeof options.typescript === 'object' &&
+    'version' in options.typescript
+  ) {
     return require('ts-plugin-next').createTSPlugin(options)
   }
 

packages/ts-next-plugin/README.md

@@ -9,9 +9,9 @@ This is a TypeScript Language Server plugin for the Next.js app directory.
 - Error ts(71016): the `'use client'` directive is used at the same time as `'use server'` directive
 - Error ts(71015): the `'use server'` directive must be above all other expressions
 - Error ts(71011): validates that server files can only export async functions
-- Error ts(71001): the following `react` and `react-dom` APIs are not allowed in Server Components: `useState`, `useEffect`, `useLayoutEffect`, `useDeferredValue`, `useImperativeHandle`, `useInsertionEffect`, `useReducer`, `useRef`, `useSyncExternalStore`, `useTransition`, `Component`, `PureComponent`, `createContext`, `createFactory`, `experimental_useOptimistic`, `useOptimistic`, and `useActionState`.
-- Hide autocompletions for disallowed APIs such as `useState`
-- Show errors if disallowed APIs such as `useState` are used
+- Error ts(71001): [`DISALLOWED_SERVER_REACT_APIS`](#glossary) are not allowed in Server Components.
+- Hide autocompletions for [`DISALLOWED_SERVER_REACT_APIS`](#glossary).
+- Modify completions for Next.js metadata (and show it higher up).
 
 ### 📺 Client Layer
 
@@ -32,5 +32,9 @@ This is a TypeScript Language Server plugin for the Next.js app directory.
 - Error ts(71002): config files can only export the values: `config`, `generateStaticParams`, `metadata`, `generateMetadata`, `viewport`, and `generateViewport`.
 - Error ts(71012): config values must match the schema
 - Error ts(71013): config values must be serializable
-- Autocompletion and docs for configs
+- Adds autocompletion and docs for configs
 - Hover hints for configs
+
+### Glossary
+
+- `DISALLOWED_SERVER_REACT_APIS` refers to: `useState`, `useEffect`, `useLayoutEffect`, `useDeferredValue`, `useImperativeHandle`, `useInsertionEffect`, `useReducer`, `useRef`, `useSyncExternalStore`, `useTransition`, `Component`, `PureComponent`, `createContext`, `createFactory`, `experimental_useOptimistic`, `useOptimistic`, and `useActionState`

packages/ts-next-plugin/TSNextPlugin.ts

@@ -1,6 +1,6 @@
 import path from 'path'
 import ts from 'typescript'
-import { NEXT_TS_ERRORS } from './constant'
+import { NEXT_TS_ERRORS, USE_CLIENT, USE_SERVER } from './constant'
 
 export class DirectiveError extends Error {
   category: ts.Diagnostic['category']
@@ -92,7 +92,7 @@ export class TSNextPlugin {
           ts.isExpressionStatement(node) &&
           ts.isStringLiteral(node.expression)
         ) {
-          if (node.expression.text === 'use client') {
+          if (node.expression.text === USE_CLIENT) {
             if (isDirective) {
               isClientEntry = true
             } else {
@@ -106,7 +106,7 @@ export class TSNextPlugin {
             }
           }
 
-          if (node.expression.text === 'use server') {
+          if (node.expression.text === USE_SERVER) {
             if (isDirective) {
               isServerEntry = true
             } else {

packages/ts-next-plugin/constant.ts

@@ -310,3 +310,6 @@ export const API_DOCS: Record<string, APIDoc> = {
     },
   },
 } satisfies Record<string, APIDoc>
+
+export const USE_CLIENT = 'use client'
+export const USE_SERVER = 'use server'

packages/ts-next-plugin/createTSPlugin.ts

@@ -8,7 +8,7 @@ export const createTSPlugin: ts.server.PluginModuleFactory = () => {
 
     const virtualFiles: Record<
       string,
-      { file: ts.IScriptSnapshot; ver: number }
+      { scriptSnapshot: ts.IScriptSnapshot; ver: number }
     > = {}
 
     const getScriptVersion = info.languageServiceHost.getScriptVersion.bind(
@@ -32,9 +32,9 @@ export const createTSPlugin: ts.server.PluginModuleFactory = () => {
       const file = virtualFiles[fileName]
       if (!file) return getScriptSnapshot(fileName)
       tsNextPlugin.log(
-        `[ProxiedLSHost] getScriptSnapshot(${fileName}) - ${JSON.stringify(file.file, null, 2)}`
+        `[ProxiedLSHost] getScriptSnapshot(${fileName}) - ${JSON.stringify(file.scriptSnapshot, null, 2)}`
       )
-      return file.file
+      return file.scriptSnapshot
     }
 
     const getScriptFileNames = info.languageServiceHost.getScriptFileNames.bind(
@@ -64,7 +64,7 @@ export const createTSPlugin: ts.server.PluginModuleFactory = () => {
       tsNextPlugin.log(`[ProxiedLSHost] readFile(${fileName})`)
       const file = virtualFiles[fileName]
       return file
-        ? file.file.getText(0, file.file.getLength())
+        ? file.scriptSnapshot.getText(0, file.scriptSnapshot.getLength())
         : readFile(fileName)
     }
 
@@ -90,9 +90,9 @@ export const createTSPlugin: ts.server.PluginModuleFactory = () => {
       const existing = virtualFiles[fileName]
       if (existing) {
         virtualFiles[fileName].ver++
-        virtualFiles[fileName].file = snap
+        virtualFiles[fileName].scriptSnapshot = snap
       } else {
-        virtualFiles[fileName] = { ver: 2, file: snap }
+        virtualFiles[fileName] = { ver: 2, scriptSnapshot: snap }
       }
 
       // This is the same function call that the Svelte TS plugin makes

packages/ts-next-plugin/proxy.ts

@@ -48,30 +48,31 @@ export const createProxy = (tsNextPlugin: TSNextPlugin) => {
       entries: [],
     }
 
-    if (!tsNextPlugin.isAppEntryFile(fileName)) return prior
+    if (!tsNextPlugin.isAppEntryFile(fileName)) {
+      return prior
+    }
 
-    // If it's a server entry.
     const { isClientEntry } = tsNextPlugin.getEntryInfo(fileName, {
       throwOnInvalidDirective: false,
     })
+
     if (!isClientEntry) {
-      // Remove specified entries from completion list
       prior.entries = server.filterCompletionsAtPosition(prior.entries)
 
-      // Provide autocompletion for metadata fields
-      prior = metadata.filterCompletionsAtPosition(
+      prior = metadata.modifyCompletionsAtPosition(
         fileName,
         position,
         options,
         prior
       )
     }
 
-    // Add auto completions for export configs.
     config.addCompletionsAtPosition(fileName, position, prior)
 
     const source = tsNextPlugin.getSource(fileName)
-    if (!source) return prior
+    if (!source) {
+      return prior
+    }
 
     ts.forEachChild(source!, (node) => {
       // Auto completion for default export function's props.
@@ -88,7 +89,6 @@ export const createProxy = (tsNextPlugin: TSNextPlugin) => {
     return prior
   }
 
-  // Show auto completion details
   proxy.getCompletionEntryDetails = (
     fileName: string,
     position: number,
@@ -102,7 +102,9 @@ export const createProxy = (tsNextPlugin: TSNextPlugin) => {
       entryName,
       data
     )
-    if (entryCompletionEntryDetails) return entryCompletionEntryDetails
+    if (entryCompletionEntryDetails) {
+      return entryCompletionEntryDetails
+    }
 
     const metadataCompletionEntryDetails = metadata.getCompletionEntryDetails(
       fileName,
@@ -113,7 +115,9 @@ export const createProxy = (tsNextPlugin: TSNextPlugin) => {
       preferences,
       data
     )
-    if (metadataCompletionEntryDetails) return metadataCompletionEntryDetails
+    if (metadataCompletionEntryDetails) {
+      return metadataCompletionEntryDetails
+    }
 
     return info.languageService.getCompletionEntryDetails(
       fileName,
@@ -126,13 +130,14 @@ export const createProxy = (tsNextPlugin: TSNextPlugin) => {
     )
   }
 
-  // Quick info
   proxy.getQuickInfoAtPosition = (fileName: string, position: number) => {
     const prior = info.languageService.getQuickInfoAtPosition(
       fileName,
       position
     )
-    if (!tsNextPlugin.isAppEntryFile(fileName)) return prior
+    if (!tsNextPlugin.isAppEntryFile(fileName)) {
+      return prior
+    }
 
     // Remove type suggestions for disallowed APIs in server components.
     const { isClientEntry } = tsNextPlugin.getEntryInfo(fileName, {
@@ -148,20 +153,25 @@ export const createProxy = (tsNextPlugin: TSNextPlugin) => {
       }
 
       const metadataInfo = metadata.getQuickInfoAtPosition(fileName, position)
-      if (metadataInfo) return metadataInfo
+      if (metadataInfo) {
+        return metadataInfo
+      }
     }
 
     const overridden = config.getQuickInfoAtPosition(fileName, position)
-    if (overridden) return overridden
+    if (overridden) {
+      return overridden
+    }
 
     return prior
   }
 
-  // Show errors for disallowed imports
   proxy.getSemanticDiagnostics = (fileName: string) => {
     const prior = info.languageService.getSemanticDiagnostics(fileName)
     const source = tsNextPlugin.getSource(fileName)
-    if (!source) return prior
+    if (!source) {
+      return prior
+    }
 
     let isClientEntry = false
     let isServerEntry = false
@@ -342,7 +352,9 @@ export const createProxy = (tsNextPlugin: TSNextPlugin) => {
         fileName,
         position
       )
-      if (metadataDefinition) return metadataDefinition
+      if (metadataDefinition) {
+        return metadataDefinition
+      }
     }
 
     return info.languageService.getDefinitionAndBoundSpan(fileName, position)

packages/ts-next-plugin/rules/client-boundary.ts

@@ -22,6 +22,7 @@ export const clientBoundary = (tsNextPlugin: TSNextPlugin) => ({
         }
       }
     }
+
     return diagnostics
   },