TypeScript Plugin

Overview

The Next.js TypeScript plugin acts as an integrated language service extension that enhances the developer experience within the app directory by enforcing correct file conventions, validating segment configuration exports, and policing component boundaries. It provides intelligent autocompletion, hover hints, and diagnostic error checking directly inside editors supporting the TypeScript Language Service protocol. Sources: packages/next/src/server/typescript/index.ts:1-10

By proxying language service requests, the plugin intercepts semantic diagnostics, completion entries, and quick info lookups to restrict unauthorized React APIs in server components, validate route segment options, verify serialization constraints for "use client" and "use server" boundaries, and enforce proper component signatures. Sources: packages/next/src/server/typescript/index.ts:60-175, packages/next/src/server/typescript/index.ts:178-270

Language service plugin architecture

Plugin Initialization and Request Proxying

The Next.js TypeScript plugin exports a createTSPlugin function adhering to the tsModule.server.PluginModuleFactory signature. It receives a factory context containing the TypeScript module reference and returns an inner create closure taking a tsModule.server.PluginCreateInfo object. The plugin checks user configurations in tsconfig.json through info.config.enabled, defaulting to true. If disabled, it immediately returns the unmodified language service. When enabled, it calls init with the TypeScript module and creation info to set up project directory boundaries and regular expression matching for the app directory. Sources: packages/next/src/server/typescript/index.ts:31-48, packages/next/src/server/typescript/utils.ts:15-27

To intercept language service queries without breaking standard editing features, the plugin establishes a decorated proxy object using Object.create(null) and iterates over all keys of info.languageService. Each method is wrapped to delegate execution back to the underlying language service instance. Specific handlers such as getCompletionsAtPosition, getCompletionEntryDetails, getQuickInfoAtPosition, and getSemanticDiagnostics are overridden to inject custom diagnostics, filter out disallowed completions, or modify quick info tooltips for Next.js app directory files. Sources: packages/next/src/server/typescript/index.ts:51-176, packages/next/src/server/typescript/index.ts:178-270

Call-Chain Execution Walkthrough: create to log

During semantic diagnostics collection or entry analysis, the plugin executes the explicit call chain create() → getEntryInfo() → getSource() → log(). When diagnostic checking evaluates a file via getSemanticDiagnostics, it invokes getEntryInfo(fileName, true) from packages/next/src/server/typescript/index.ts:187. getEntryInfo() immediately calls getSource(fileName) from packages/next/src/server/typescript/utils.ts:122 to query the language service program for the file's AST SourceFile. When initialization runs, init() invokes log(message) from packages/next/src/server/typescript/utils.ts:26 to record plugin status through the project service logger. Sources: packages/next/src/server/typescript/index.ts:187-190, packages/next/src/server/typescript/utils.ts:10-12, packages/next/src/server/typescript/utils.ts:26-26, packages/next/src/server/typescript/utils.ts:51-58, packages/next/src/server/typescript/utils.ts:118-123

Sources: packages/next/src/server/typescript/index.ts:187-190, packages/next/src/server/typescript/utils.ts:10-12, packages/next/src/server/typescript/utils.ts:26-26, packages/next/src/server/typescript/utils.ts:51-58, packages/next/src/server/typescript/utils.ts:118-123

AST Utilities and Request Dispatching

The plugin provides helper functions in utils.ts to inspect Abstract Syntax Tree nodes and evaluate file paths against the app directory structure. Path validation relies on appDirRegExp, generated dynamically from the project's current working directory to match both standard app folders and src/app layouts. Sources: packages/next/src/server/typescript/utils.ts:19-27, packages/next/src/server/typescript/utils.ts:101-115

Sources: packages/next/src/server/typescript/utils.ts:15-181

Segment config validation and completion

Segment Configuration Validation and Autocompletion

The TypeScript plugin validates route segment configurations and allowed entry exports within Next.js application files. It verifies variable declarations against a defined schema of allowed entry identifiers and reports semantic errors when invalid configuration options or values are supplied. Sources: packages/next/src/server/typescript/rules/config.ts:1-28, packages/next/src/server/typescript/rules/config.ts:620-642

Sources: packages/next/src/server/typescript/constant.ts:15-24

Metadata Import Code Actions

When autocompleting or inspecting metadata or generateMetadata entry points, the plugin checks the target source file for an existing type import from the 'next' module. If no import for Metadata is present, it provides an automatic code action to inject import type { Metadata } from 'next'; directly beneath top-level directive strings such as "use client". Sources: packages/next/src/server/typescript/rules/config.ts:504-602

Client boundary restrictions and diagnostics

Validating Client Component Props and Serializability

The TypeScript plugin inspects variable statements and function declarations in files carrying the "use client" directive to verify that component props adhere to serialization constraints. When analyzing function parameters, the plugin evaluates type literal members to detect non-serializable property types such as functions, constructors, and class declarations, emitting diagnostic warnings when invalid prop types are supplied across client boundaries. Sources: packages/next/src/server/typescript/rules/client-boundary.ts:7-49

Copyexport const NEXT_TS_ERRORS = {
  INVALID_SERVER_API: 71001,
  INVALID_ENTRY_EXPORT: 71002,
  INVALID_OPTION_VALUE: 71003,
  MISPLACED_ENTRY_DIRECTIVE: 71004,
  INVALID_PAGE_PROP: 71005,
  INVALID_CONFIG_OPTION: 71006,
  INVALID_CLIENT_ENTRY_PROP: 71007,
  INVALID_METADATA_EXPORT: 71008,
  INVALID_ERROR_COMPONENT: 71009,
  INVALID_ENTRY_DIRECTIVE: 71010,
  INVALID_SERVER_ENTRY_RETURN: 71011,
}

Sources: packages/next/src/server/typescript/constant.ts:1-13

Server Actions and Error Boundary Exceptions

To accommodate legitimate callback patterns and framework integrations, the plugin applies specific naming and file-path heuristics before raising serializability diagnostics on function-typed props. Properties named action or ending with Action (such as formAction) are permitted under the assumption that they represent Server Actions. Additionally, files matching error.tsx or global-error.tsx are evaluated against framework-injected recovery functions (reset and retry), exempting them from client component serialization rules. Sources: packages/next/src/server/typescript/rules/client-boundary.ts:43-87

Server actions and boundaries validation

Verifying Async Signatures in Server Modules

The TypeScript plugin validates files governed by the "use server" directive to ensure that all exported entities conform to asynchronous execution requirements. Using the type checker, the plugin inspects export declarations, variable statements, arrow functions, function declarations, function expressions, call expressions, and identifiers to verify that every exported member returns a Promise. Sources: packages/next/src/server/typescript/rules/server-boundary.ts:1-157

Copyfunction isPromiseType(type: tsModule.Type, typeChecker: tsModule.TypeChecker) {
  const typeReferenceType = type as tsModule.TypeReference
  if (!typeReferenceType.target) return false
 
  // target should be Promise or Promise<...>
  if (
    !/^Promise(<.+>)?$/.test(typeChecker.typeToString(typeReferenceType.target))
  ) {
    return false
  }
 
  return true
}

Sources: packages/next/src/server/typescript/rules/server-boundary.ts:8-20

Server Layer Component Restrictions

Within server components, the language service plugin filters completion entries and inspects import declarations to prevent the usage of disallowed client-side React hooks and class APIs. When processing import declarations from "react" or "react-dom", the plugin checks named bindings against explicit blacklists of client APIs such as state and effect hooks. Sources: packages/next/src/server/typescript/rules/server.ts:1-90

Sources: packages/next/src/server/typescript/constant.ts:28-52, packages/next/src/server/typescript/rules/server.ts:48-86

Entry point and error conventions

Page and Layout Component Parameter Validation

The language service plugin validates entry point components by inspecting the parameters of default export function declarations in page and layout files. For page entries determined via isPageFile, parameters are restricted to params and searchParams. For layout entries, the plugin reads the current directory using fs.readdirSync with withFileTypes: true to discover any directory names starting with @, which represent parallel route slots. These slot names are sliced and appended to the allowed layout properties. Sources: packages/next/src/server/typescript/rules/entry.ts:13-58, packages/next/src/server/typescript/rules/entry.ts:112-139

When semantic diagnostics are evaluated for an entry component, the plugin iterates over object binding pattern elements in the function parameters. If an element name is not included in the valid properties list, a diagnostic error is pushed with code NEXT_TS_ERRORS.INVALID_PAGE_PROP and message text specifying that the property is not a valid page or layout prop. Sources: packages/next/src/server/typescript/rules/entry.ts:112-161

Copyconst diagnostics: tsModule.Diagnostic[] = []
 
const props = node.parameters?.[0]?.name
if (props && ts.isObjectBindingPattern(props)) {
  for (const prop of props.elements) {
    const propName = (prop.propertyName || prop.name).getText()
    if (!validProps.includes(propName)) {
      diagnostics.push({
        file: source,
        category: ts.DiagnosticCategory.Error,
        code: NEXT_TS_ERRORS.INVALID_PAGE_PROP,
        messageText: `"${propName}" is not a valid ${type} prop.`,
        start: prop.getStart(),
        length: prop.getWidth(),
      })
    }
  }
}
 
return diagnostics

Sources: packages/next/src/server/typescript/rules/entry.ts:141-160

Error Boundary Client Directive Enforcement

The error entry rule module inspects files matching the pattern error.tsx? or global-error.tsx? to enforce that error boundaries are designated client components. If the isClientEntry flag passed to getSemanticDiagnostics is false, the plugin immediately returns a diagnostic error for the entire file. Sources: packages/next/src/server/typescript/rules/error.ts:7-34

Copyif (!isClientEntry) {
  // Error components must be Client Components
  return [
    {
      file: source,
      category: ts.DiagnosticCategory.Error,
      code: NEXT_TS_ERRORS.INVALID_ERROR_COMPONENT,
      messageText: `Error Components must be Client Components, please add the "use client" directive: https://nextjs.org/docs/app/api-reference/file-conventions/error`,
      start: 0,
      length: source.text.length,
    },
  ]
}

Sources: packages/next/src/server/typescript/rules/error.ts:19-31

Metadata Typing and Export Restrictions

The metadata rule module handles semantic validation for metadata and generateMetadata exports across both client and server boundaries. In client entries, exporting either symbol via variable statements, function declarations, or export declarations results in NEXT_TS_ERRORS.INVALID_METADATA_EXPORT errors stating that these APIs are forbidden in Client Components. Sources: packages/next/src/server/typescript/rules/metadata.ts:6-74

In server entries, the plugin checks whether metadata or generateMetadata exports carry proper type annotations using the helper function hasType. If a server component exports generateMetadata or metadata without an explicit return type or variable type annotation, a warning diagnostic is generated recommending the appropriate Metadata or Promise<Metadata> type from "next". Sources: packages/next/src/server/typescript/rules/metadata.ts:75-242, packages/next/src/server/typescript/rules/metadata.ts:244-281

Copyfunction hasType(node: tsModule.Declaration): boolean {
  const ts = getTs()
 
  if (
    !ts.isVariableDeclaration(node) &&
    !ts.isFunctionDeclaration(node) &&
    !ts.isArrowFunction(node) &&
    !ts.isFunctionExpression(node)
  ) {
    return false
  }
 
  // For function declarations, expressions, and arrow functions, check if they have return type
  if (
    ts.isFunctionDeclaration(node) ||
    ts.isFunctionExpression(node) ||
    ts.isArrowFunction(node)
  ) {
    return !!node.type
  }
 
  // For variable declarations
  if (!node.name) return false
  const name = node.name.getText()
  if (name === 'generateMetadata') {
    // If it's a function expression or arrow function, check if it has return type
    if (
      node.initializer &&
      (ts.isFunctionExpression(node.initializer) ||
        ts.isArrowFunction(node.initializer))
    ) {
      return !!node.initializer.type
    }
  }
 
  // For all other cases, check if the node has a type annotation
  return !!node.type
}

Sources: packages/next/src/server/typescript/rules/metadata.ts:244-281

Build typegen and configuration verification

Next Types Plugin Artifact Generation and Route Typing

During compilation, Next.js generates TypeScript artifacts inside the .next/types directory to validate layouts, pages, and route handlers. The NextTypesPlugin creates type-guard files that import entry modules and verify their exported fields, parameters, and return types against strict schema definitions using the checkFields and Diff utility types. Sources: packages/next/src/build/webpack/plugins/next-types-plugin/index.ts:11-88

Copyfunction createTypeGuardFile(
  fullPath: string,
  relativePath: string,
  options: {
    type: 'layout' | 'page' | 'route'
    slots?: string[]
  }
) {
  return `// File: ${fullPath}
import * as entry from '${relativePath}.js'
${
  options.type === 'route'
    ? `import type { NextRequest } from 'next/server.js'`
    : `import type { ResolvingMetadata, ResolvingViewport } from 'next/dist/lib/metadata/types/metadata-interface.js'`
}
 
import type { InstantConfigForTypeCheckInternal, Prefetch, EnsureStatic } from 'next/dist/build/segment-config/app/app-segment-config.js'
 
type TEntry = typeof import('${relativePath}.js')
 
type SegmentParams<T extends Object = any> = T extends Record<string, any>
  ? { [K in keyof T]: T[K] extends string ? string | string[] | undefined : never }
  : T
 
// Check that the entry is a valid entry
checkFields<Diff<{
  ${
    options.type === 'route'
      ? HTTP_METHODS.map((method) => `${method}?: Function`).join('\n  ')
      : 'default: Function'
  }
  config?: {}
  generateStaticParams?: Function
  ${options.type === 'route' ? '' : 'unstable_paramMatching?: {}\n  unstable_generateParamMatching?: Function'}
  instant?: InstantConfigForTypeCheckInternal
  prefetch?: Prefetch
  ensureStatic?: EnsureStatic
  unstable_dynamicStaleTime?: number
  revalidate?: RevalidateRange<TEntry> | false
  dynamic?: 'auto' | 'force-dynamic' | 'error' | 'force-static'
  dynamicParams?: boolean
  fetchCache?: 'auto' | 'force-no-store' | 'only-no-store' | 'default-no-store' | 'default-cache' | 'only-cache' | 'force-cache'
  /** @deprecated The \`preferredRegion\` config is deprecated. Remove this export. */
  preferredRegion?: 'auto' | 'global' | 'home' | string | string[]
  runtime?: 'nodejs' | 'experimental-edge' | 'edge'
  maxDuration?: number
  ${
    options.type === 'route'
      ? ''
      : `
  metadata?: any
  generateMetadata?: Function
  viewport?: any
  generateViewport?: Function
  `
  }
}, TEntry, ''>>()
 

Sources: packages/next/src/build/webpack/plugins/next-types-plugin/index.ts:31-88

For App Router route handlers, the type generator verifies that HTTP methods receive a Request or NextRequest as their first argument and a RouteContext containing params as their second argument, while returning a Response, void, never, or a Promise resolving to them. For pages and layouts, it checks PageProps and LayoutProps alongside generateStaticParams, generateMetadata, and generateViewport. Sources: packages/next/src/build/webpack/plugins/next-types-plugin/index.ts:89-180

Copy    : `// Check the prop type of the entry function
checkFields<Diff<${
        options.type === 'page' ? 'PageProps' : 'LayoutProps'
      }, FirstArg<TEntry['default']>, 'default'>>()
 
// Check the arguments and return type of the generateMetadata function
if ('generateMetadata' in entry) {
  checkFields<Diff<${
    options.type === 'page' ? 'PageProps' : 'LayoutProps'
  }, FirstArg<MaybeField<TEntry, 'generateMetadata'>>, 'generateMetadata'>>()
  checkFields<Diff<ResolvingMetadata, SecondArg<MaybeField<TEntry, 'generateMetadata'>>, 'generateMetadata'>>()
}
 
// Check the arguments and return type of the generateViewport function
if ('generateViewport' in entry) {
  checkFields<Diff<${
    options.type === 'page' ? 'PageProps' : 'LayoutProps'
  }, FirstArg<MaybeField<TEntry, 'generateViewport'>>, 'generateViewport'>>()
  checkFields<Diff<ResolvingViewport, SecondArg<MaybeField<TEntry, 'generateViewport'>>, 'generateViewport'>>()
}
`
}
// Check the arguments and return type of the generateStaticParams function
if ('generateStaticParams' in entry) {
  checkFields<Diff<{ params: SegmentParams }, FirstArg<MaybeField<TEntry, 'generateStaticParams'>>, 'generateStaticParams'>>()
  checkFields<Diff<{ __tag__: 'generateStaticParams', __return_type__: any[] | Promise<any[]> }, { __tag__: 'generateStaticParams', __return_type__: ReturnType<MaybeField<TEntry, 'generateStaticParams'>> }>>()
}
 
export interface PageProps {
  params?: Promise<SegmentParams>
  searchParams?: Promise<any>
}
export interface LayoutProps {
  children?: React.ReactNode
${
  options.slots
    ? options.slots.map((slot) => `  ${slot}: React.ReactNode`).join('\n')
    : ''
}
  params?: Promise<SegmentParams>
}
 

Sources: packages/next/src/build/webpack/plugins/next-types-plugin/index.ts:139-180

Tsconfig Verification and Configuration Defaults

The setup verification pipeline inspects the project's tsconfig.json file, automatically writing configuration defaults and injecting required compiler options and plugins via writeConfigurationDefaults. If a user project extends an external configuration or specifies explicit paths, the setup utility adapts or warns about manual steps. Sources: packages/next/src/lib/verify-typescript-setup.ts:231-252, packages/next/src/lib/typescript/writeConfigurationDefaults.ts:205-240

Copyexport async function writeConfigurationDefaults(
  typescriptVersion: string,
  tsConfigPath: string,
  isFirstTimeSetup: boolean,
  hasAppDir: boolean,
  distDir: string,
  hasPagesDir: boolean,
  strictRouteTypes: boolean
): Promise<void> {
  if (isFirstTimeSetup) {
    writeFileSync(tsConfigPath, '{}' + os.EOL)
  }
 
  const userTsConfigContent = readFileSync(tsConfigPath, 'utf8')
  const userTsConfig = CommentJson.parse(userTsConfigContent)
 
  // Bail automatic setup when the user has extended or referenced another config
  if ('extends' in userTsConfig || 'references' in userTsConfig) {
    return
  }
 
  if (userTsConfig?.compilerOptions == null) {
    userTsConfig.compilerOptions = {}
    isFirstTimeSetup = true
  }
 
  const desiredCompilerOptions = getDesiredCompilerOptions(
    typescriptVersion,
    userTsConfig
  )
 
  const suggestedActions: string[] = []
  const requiredActions: string[] = []
  for (const optionKey in desiredCompilerOptions) {
    const check = desiredCompilerOptions[optionKey]
    if ('suggested' in check) {

Sources: packages/next/src/lib/typescript/writeConfigurationDefaults.ts:205-240

The desired compiler options shape enforces specific values for module resolution, target, JSX runtime, and incremental compilation to match Next.js SWC and webpack build semantics. The table below lists the required and suggested compiler options enforced or injected by the configuration utility:

Sources: packages/next/src/lib/typescript/writeConfigurationDefaults.ts:52-144

Related

• Build Pipeline