O ficheiro tsconfig.json

O ficheiro tsconfig.json é o principal ficheiro de configuração de um projeto TypeScript. Ele define quais os ficheiros que devem ser incluídos e quais opções de compilação o compilador TypeScript (tsc) deve usar para transformar o código TypeScript (.ts) em JavaScript.

Este ficheiro é criado com a instrução

npx tsc --init

aquando da criação do projeto.

Funções do tsconfig.json

• Especificar os ficheiros raiz do projeto e padrões para inclusão/exclusão de ficheiros.
• Definir opções do compilador por meio da propriedade compilerOptions, como a versão de JavaScript a ser gerada (target), o sistema de módulos utilizado (module), a pasta de saída dos arquivos compilados (outDir), regras de verificação de tipos, entre outras.
• Permitir uma configuração consistente de compilação para toda a equipe e ferramentas utilizadas no projeto, como editores, linters e frameworks.
• Indicar ao TypeScript que o diretório onde ele está presente é a raiz do projeto.

Exemplo de estrutura básica

{
  "compilerOptions": {
    "target": "es2019",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

O uso do tsconfig.json é essencial para um fluxo de trabalho eficiente e controlado em projetos TypeScript, tornando mais simples compilar, depurar e integrar com outras ferramentas do ecossistema JavaScript e TypeScript.

Exemplo de uma configuração com opções essenciais

Para configurar as opções essenciais no campo compilerOptions do ficheiro tsconfig.json num projeto TypeScript, recomenda-se definir um conjunto de propriedades que garantam compatibilidade, segurança de tipos e organização do código. Aqui estão as principais configurações essenciais:

{
  "compilerOptions": {
    "target": "es6",                 // Versão do JavaScript de saída (ES6 é amplamente suportado)
    "module": "commonjs",            // Tipo de sistema de módulos (CommonJS para Node.js)
    "outDir": "./dist",              // Diretório para os ficheiros compilados
    "rootDir": "./src",              // Diretório das fontes TypeScript
    "strict": true,                  // Habilita todas as verificações estritas de tipo (recomendado para segurança)
    "esModuleInterop": true,         // Permite interoperabilidade entre módulos CommonJS e ES Modules
    "skipLibCheck": true,             // Ignora checagem de tipos em bibliotecas externas (.d.ts)
    "forceConsistentCasingInFileNames": true // Força nomes de ficheiros com mesmo padrão de letras (maiúsc/minúsc)
  },
  "include": ["src/**/*"],            // Ficheiros a incluir
  "exclude": ["node_modules"]         // ficheiros a excluir
}

Explicação das opções-chave

target: Define para qual versão do JavaScript o TypeScript será compilado. ES6 (ES2015) é uma escolha moderna e compatível com a maioria dos ambientes.

Alguns valores possíveis sáo:

• "es3": ECMAScript 3 (padrão antigo, raramente usado hoje em dia)
• "es5": ECMAScript 5 (amplamente suportado, usado para compatibilidade com navegadores antigos)
• "es6" ou "es2015": ECMAScript 2015 (primeira grande atualização do JS com classes, arrow functions, etc.)
• "es2016": ECMAScript 2016
• "es2017": ECMAScript 2017 (async/await nativo)
• "es2018": ECMAScript 2018
• "es2019": ECMAScript 2019
• "es2020": ECMAScript 2020
• "es2021": ECMAScript 2021
• "es2022": ECMAScript 2022
• "esnext": A última versão do ECMAScript suportada pelo compilador TypeScript, com os recursos mais recentes e experimentais.

module: Define o sistema de módulos usado. No Node.js, o padrão mais comum é commonjs.

Alguns valores possíveis são:

• "none": Não emite código de módulos.
• "commonjs": Usa o sistema CommonJS (require/module.exports), padrão no Node.js tradicional.
• "amd": Para carregadores de módulos AMD (Asynchronous Module Definition).
• "system": Para o carregador SystemJS.
• "umd": Universal Module Definition, suporta AMD e CommonJS.
• "es6" ou "es2015": Usa módulos ECMAScript 2015 (ESM) com import/export.
• "esnext": Usa a última versão suportada do padrão ECMAScript para módulos (sempre a mais recente).
• "node16": Módulos Node.js com suporte explícito para extensão de arquivo e resolução usada no Node.js 16.
• "nodenext": Versão avançada para Node.js moderno (versão 12+), com interoperabilidade entre CommonJS e ESM, respeitando extensões .mts, .cts e o campo "type" no package.json.

outDir e rootDir: Organizam a estrutura dos arquivos compilados, separando código-fonte .ts do código JavaScript gerado.

strict: Liga várias opções que reforçam a segurança de tipo, reduzindo erros comuns durante o desenvolvimento.

esModuleInterop: Permite a importação facilitada de módulos CommonJS, melhorando a compatibilidade.

skipLibCheck: Foca a verificação nos arquivos do projeto e ignora arquivos de declaração de terceiros, acelerando a compilação.

forceConsistentCasingInFileNames: Evita problemas em sistemas de arquivos que diferenciam maiúsculas de minúsculas.

Essas opções formam uma base sólida para a maioria dos projetos TypeScript, promovendo código consistente, seguro e organizado.