close
Skip to content
NextjsLogotypeNextjsLogotype
Select a display theme:
This page is also available as Markdown: request this page's URL with an Accept: text/markdown header. For an index of Next.js documentation, see /docs/llms.txt.

useTypeScriptCli

This feature is currently experimental and subject to change, it's not recommended for production. Try it out and share your feedback on GitHub.
Last updated August 3, 2026

By default, next build runs the project-local tsc command instead of loading the TypeScript JavaScript compiler API. This supports TypeScript 6 and enables TypeScript 7 while its JavaScript API is unavailable.

Install TypeScript 7 in your project:

Terminal
pnpm add -D typescript@^7

The CLI checker is enabled by default. To use the TypeScript JavaScript compiler API instead, set experimental.useTypeScriptCli to false:

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    useTypeScriptCli: false,
  },
}
 
export default nextConfig

If you opt out while using TypeScript 7, next build exits because the TypeScript JavaScript compiler API is unavailable.

Behavior

  • Next.js continues to generate next-env.d.ts and route types and to apply its recommended tsconfig settings before running the checker.
  • TypeScript diagnostics are printed directly from tsc. Next.js-specific code frames and error rewriting are not applied.
  • The complete project selected by the configured tsconfig file is checked, including test files and .next/dev/types when included. The --debug-build-paths option does not limit this set and produces a warning when combined with the CLI checker.
  • typescript.tsconfigPath selects the project passed to tsc.
  • typescript.ignoreBuildErrors skips the type-checking step, including the CLI checker.

Learn more about using TypeScript 7 with Next.js.

Edit this page on GitHub

Was this helpful?

supported.