This page is also available as Markdown: request this page's URL with an Accept: text/markdown header. For an index of Next.js Pages Router documentation, see /docs/pages/llms.txt.

You are currently viewing the documentation for Pages Router.

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 July 10, 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.