Capítulo 262 de 456

useTypeScriptCli

Core Idea

Controla se next build faz type checking rodando o tsc local do projeto via CLI (default) em vez de carregar a API JavaScript do compiler TypeScript. Isso é o que permite suporte a TypeScript 6 e habilita TypeScript 7 (que ainda não expõe a API JS).

Key Concepts

  • experimental.useTypeScriptCli: boolean, default true (CLI checker habilitado). Setar false volta a usar a API JS do compiler TypeScript.
  • TypeScript 7: requer typescript@^7 instalado; se você desabilitar useTypeScriptCli enquanto estiver no TS7, next build falha (API JS do compiler indisponível nessa versão).
  • Comportamento do CLI checker: imprime diagnostics nativos do tsc diretamente, sem os code frames/rewriting de erro específicos do Next.js. Checa o projeto completo selecionado pelo tsconfig (incluindo test files e .next/dev/types); next build --debug-build-paths não restringe esse conjunto e gera warning se combinado com o CLI checker.
  • typescript.tsconfigPath: continua selecionando o projeto passado ao tsc.
  • typescript.ignoreBuildErrors: pula a etapa de type-checking inteira, incluindo o CLI checker.

Code Examples

pnpm add -D typescript@^7
  • O que demonstra: instalar TypeScript 7 no projeto antes de usar o CLI checker com ele.
const nextConfig: NextConfig = {
  experimental: {
    useTypeScriptCli: false,
  },
}
  • O que demonstra: opt-out do CLI checker, voltando para a API JS do compiler (não funciona com TS7).

Key Takeaways

  1. Default mudou para usar o tsc CLI local em vez da API do compiler, é o caminho de compatibilidade com TS7.
  2. Erros impressos pelo CLI checker são o formato nativo do tsc, sem o polish de code frames do Next.js.
  3. --debug-build-paths (flag do next build) não limita o escopo de arquivos checados pelo CLI checker, e gera warning se usado junto.

Connects To

  • typescript (config/typescript e config/next-config-js/typescript): tsconfigPath e ignoreBuildErrors continuam controlando o comportamento independente de qual checker roda.
  • TypeScript > Using TypeScript 7: seção com contexto completo sobre migração para TS7.
AnterioruseOfflinePróximowebpack