Dicas do TSConfig

tsconfig.jsonassusta todo mundo. É um arquivo enorme com MUITAS opções em potencial.

Mas, na verdade, há apenas algumas opções de configuração com as quais você precisa se preocupar. Vamos descobri-las e criá-las.

Início rápido

Quer só o código? Aqui vai:

{
  "compilerOptions": {
    /* Base Options: */
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true,
    "verbatimModuleSyntax": true,

    /* Strictness */
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,

    /* If transpiling with TypeScript: */
    "module": "NodeNext",
    "outDir": "dist",
    "sourceMap": true,

    /* AND if you're building for a library: */
    "declaration": true,

    /* AND if you're building for a library in a monorepo: */
    "composite": true,
    "declarationMap": true,

    /* If NOT transpiling with TypeScript: */
    "module": "preserve",
    "noEmit": true,

    /* If your code runs in the DOM: */
    "lib": ["es2022", "dom", "dom.iterable"],

    /* If your code doesn't run in the DOM: */
    "lib": ["es2022"]
  }
}

Explicação completa

Opções básicas

Aqui estão as opções básicas que recomendo para todos os projetos.

{
  "compilerOptions": {
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true,
    "verbatimModuleSyntax": true
  }
}

• esModuleInterop: Ajuda a consertar algumas barreiras entre o CommonJS e os Módulos ES.
• skipLibCheck: Ignora a verificação dos tipos de .d.tsarquivos. Isso é importante para o desempenho, porque, caso contrário, todos node_modulesserão verificados.
• target: A versão do JavaScript que você está almejando. Recomendo es2022over esnextpara estabilidade.
• allowJs e resolveJsonModule: Permite que você importe .jse .jsonarquivos. Sempre útil.
• moduleDetection: Esta opção força o TypeScript a considerar todos os arquivos como módulos. Isso ajuda a evitar erros ‘ cannot redeclare block-scoped variable ‘.
• isolatedModules: Esta opção evita alguns recursos do TS que não são seguros ao tratar módulos como arquivos isolados.
• verbatimModuleSyntax: Esta opção força você a usar import typeand export type, levando a um comportamento mais previsível e menos importações desnecessárias. Com module: NodeNext, ela também força você a usar a sintaxe de importação correta para ESM ou CJS.

Rigor

Aqui estão as opções de rigor que recomendo para todos os projetos.

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true
  }
}

• strict: Habilita todas as opções de verificação de tipo estrito. Indispensável.
• noUncheckedIndexedAccess: Impede que você acesse um array ou objeto sem primeiro verificar se ele está definido. Esta é uma ótima maneira de evitar erros de tempo de execução e realmente deveria ser incluída em strict.
• noImplicitOverride: Torna a overridepalavra-chave realmente útil nas aulas.

Muitas pessoas recomendaram as opções de rigor em tsconfig/bases, um repositório maravilhoso que cataloga as opções do TSConfig. Essas opções incluem muitas regras que considero muito “barulhentas”, como noImplicitReturns, noUnusedLocals, noUnusedParameters, e noFallthroughCasesInSwitch. Recomendo que você adicione essas regras ao seu tsconfig.jsononly se quiser.

Transpilando com TypeScript

Se você estiver transpilando seu código (criando arquivos JavaScript) com tsc, você vai querer essas opções.

{
  "compilerOptions": {
    "module": "NodeNext",
    "outDir": "dist"
  }
}

• module: Informa ao TypeScript qual sintaxe de módulo usar. NodeNexté a melhor opção para o Node. moduleResolution: NodeNextestá implícito nesta opção.
• outDir: Informa ao TypeScript onde colocar os arquivos JavaScript compilados. disté minha convenção preferida, mas fica a seu critério.

Edifício para uma biblioteca

Se você estiver construindo para uma biblioteca, você vai querer declaration: true.

{
  "compilerOptions": {
    "declaration": true
  }
}

• declaration: Diz ao TypeScript para emitir .d.tsarquivos. Isso é necessário para que as bibliotecas possam obter autocomplete nos .jsarquivos que você está criando.

Edifício para uma biblioteca em um Monorepo

Se você estiver criando uma biblioteca em um monorepo, você também vai querer essas opções.

{
  "compilerOptions": {
    "declaration": true,
    "composite": true,
    "sourceMap": true,
    "declarationMap": true
  }
}

• composite: Diz ao TypeScript para emitir .tsbuildinfoarquivos. Isso diz ao TypeScript que seu projeto é parte de um monorepo e também o ajuda a armazenar em cache builds para rodar mais rápido.
• sourceMap e declarationMap: Diz ao TypeScript para emitir mapas de origem e mapas de declaração. Eles são necessários para que, quando os consumidores de suas bibliotecas estiverem depurando, eles possam pular para o código-fonte original usando go-to-definition.

Não transpilando com TypeScript

Se você não estiver transpilando seu código com tsc, ou seja, usando TypeScript mais como um linter, você vai querer essas opções.

{
  "compilerOptions": {
    "module": "preserve",
    "noEmit": true
  }
}

• module: preserveé a melhor opção porque imita mais de perto como os empacotadores tratam os módulos. moduleResolution: Bundlerestá implícito nesta opção.
• noEmit: Diz ao TypeScript para não emitir nenhum arquivo. Isso é importante quando você está usando um bundler para não emitir .jsarquivos inúteis.

Correndo no DOM

Se o seu código for executado no DOM, você vai querer essas opções.

{
  "compilerOptions": {
    "lib": ["es2022", "dom", "dom.iterable"]
  }
}

• lib: Informa ao TypeScript quais tipos integrados incluir. es2022é a melhor opção para estabilidade. dome dom.iterablefornece tipos para window, documentetc.

Não está em execução no DOM

Se o seu código não rodar no DOM, você vai querer lib: ["es2022"].

{
  "compilerOptions": {
    "lib": ["es2022"]
  }
}

São os mesmos acima, mas sem as tipagens dome dom.iterable.

Registro de alterações

Tenho atualizado esta folha de dicas conforme o TypeScript evolui e conforme eu refino minha visão do que pertence a um. reutilizável tsconfig.json. Aqui está o changelog:

• 2024-04-23 : Adicionado verbatimModuleSyntaxàs opções básicas. Com a introdução de module: Preserve, verbatimModuleSyntaxé muito mais útil. Muitos aplicativos fazem ‘ESM falso’, onde eles escrevem importações e exportações, mas transpilam para CommonJS. Next.js é um exemplo comum. Antes de module: Preserve, verbatimModuleSyntaxdaria erro em cada declaração de importação ou exportação porque estava esperando um módulo. Com module: Preserve, seu escopo é reduzido, garantindo import/export typeque seja usado corretamente.
• 2024-04-23 : Adicionado noImplicitOverrideàs opções de rigor. Nunca soube dessa opção, ou da overridepalavra-chave, até que descobri enquanto pesquisava meu livro. noImplicitOverrideé uma melhoria muito pequena sem custo, então por que não?