useTypeScriptCli

Core Idea

Experimental flag controlling whether next build runs the project-local tsc CLI (default) or loads the TypeScript JavaScript compiler API — needed because TypeScript 7's JS API is currently unavailable.

Key Concepts

• experimental.useTypeScriptCli (default true): CLI checker runs by default, supporting TypeScript 6 and enabling TypeScript 7 usage.
• Setting false: falls back to the JS compiler API; if TypeScript 7 is installed, next build exits because that API isn't available for TS7.
• Behavior differences: CLI checker prints raw tsc diagnostics (no Next.js code-frame rewriting); checks the full project selected by tsconfig (including test files and .next/dev/types); --debug-build-paths doesn't narrow the checked set with the CLI checker.

Code Examples

const nextConfig: NextConfig = {
  experimental: {
    useTypeScriptCli: false,
  },
}

• O que demonstra: desativa o CLI checker pra voltar à API JS do compilador TypeScript.

Anti-patterns

• Desativar a flag enquanto usa TypeScript 7: next build falha, pois a API JS não existe pra TS7.

Key Takeaways

1. Instale TypeScript 7 com npm install -D typescript@^7 pra usar o novo compilador via CLI checker.
2. typescript.tsconfigPath continua selecionando o projeto passado ao tsc; typescript.ignoreBuildErrors pula o checker inteiro (incluindo o CLI).
3. Feature experimental, comportamento pode mudar.

Connects To

• typescript (ch422): tsconfigPath e ignoreBuildErrors interagem diretamente com este checker.
• TypeScript (ch428): seção "Using TypeScript 7" cobre o mesmo tópico com mais contexto.