Módulos: TypeScript

[Histórico]

Versão	Alterações
v22.7.0	Adicionada a flag --experimental-transform-types.

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1.1 - Desenvolvimento ativo

Habilitando

Existem duas maneiras de habilitar o suporte ao TypeScript em tempo de execução no Node.js:

Suporte completo ao TypeScript

Para usar o TypeScript com suporte completo para todos os recursos do TypeScript, incluindo tsconfig.json, você pode usar um pacote de terceiros. Estas instruções usam tsx como exemplo, mas existem muitas outras bibliotecas semelhantes disponíveis.

Remoção de tipos

Adicionado em: v22.6.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1.1 - Desenvolvimento ativo

A flag --experimental-strip-types permite que o Node.js execute arquivos TypeScript. Por padrão, o Node.js executará apenas arquivos que não contenham recursos TypeScript que exigem transformação, como enums ou namespaces. O Node.js substituirá as anotações de tipo embutidas por espaços em branco, e nenhuma verificação de tipo será realizada. Para habilitar a transformação desses recursos, use a flag --experimental-transform-types. Recursos do TypeScript que dependem de configurações dentro de tsconfig.json, como caminhos ou conversão de sintaxe JavaScript mais nova para padrões mais antigos, são intencionalmente não suportados. Para obter suporte completo ao TypeScript, consulte Suporte completo ao TypeScript.

O recurso de remoção de tipos foi projetado para ser leve. Ao não suportar intencionalmente sintaxes que exigem geração de código JavaScript e ao substituir tipos embutidos por espaços em branco, o Node.js pode executar código TypeScript sem a necessidade de mapas de origem.

A remoção de tipos funciona com a maioria das versões do TypeScript, mas recomendamos a versão 5.7 ou posterior com as seguintes configurações tsconfig.json:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,
    "verbatimModuleSyntax": true
  }
}

Determinando o sistema de módulos

O Node.js suporta a sintaxe CommonJS e ES Modules em arquivos TypeScript. O Node.js não converterá de um sistema de módulos para outro; se você quiser que seu código seja executado como um módulo ES, você deve usar a sintaxe import e export, e se você quiser que seu código seja executado como CommonJS, você deve usar require e module.exports.

• Arquivos .ts terão seu sistema de módulo determinado da mesma forma que os arquivos .js. Para usar a sintaxe import e export, adicione "type": "module" ao arquivo package.json pai mais próximo.
• Arquivos .mts sempre serão executados como módulos ES, semelhante aos arquivos .mjs.
• Arquivos .cts sempre serão executados como módulos CommonJS, semelhante aos arquivos .cjs.
• Arquivos .tsx não são suportados.

Como em arquivos JavaScript, as extensões de arquivo são obrigatórias em instruções import e expressões import() : import './file.ts', não import './file'. Devido à compatibilidade com versões anteriores, as extensões de arquivo também são obrigatórias em chamadas require() : require('./file.ts'), não require('./file'), semelhante a como a extensão .cjs é obrigatória em chamadas require em arquivos CommonJS.

A opção tsconfig.json allowImportingTsExtensions permitirá que o compilador TypeScript tsc verifique a tipagem de arquivos com especificadores import que incluem a extensão .ts.

Recursos do TypeScript

Como o Node.js apenas remove tipos embutidos, qualquer recurso do TypeScript que envolva substituir a sintaxe do TypeScript por uma nova sintaxe JavaScript resultará em um erro, a menos que a flag --experimental-transform-types seja passada.

Os recursos mais importantes que exigem transformação são:

• Enum
• namespaces
• módulo legado
• propriedades de parâmetro

Como os Decorators são atualmente uma proposta TC39 Estágio 3 e em breve serão suportados pelo mecanismo JavaScript, eles não são transformados e resultarão em um erro de analisador. Esta é uma limitação temporária e será resolvida no futuro.

Além disso, o Node.js não lê arquivos tsconfig.json e não suporta recursos que dependem de configurações dentro de tsconfig.json, como caminhos ou conversão de sintaxe JavaScript mais recente para padrões mais antigos.

Importando tipos sem a palavra-chave type

Devido à natureza da remoção de tipos, a palavra-chave type é necessária para remover corretamente as importações de tipo. Sem a palavra-chave type, o Node.js tratará a importação como uma importação de valor, o que resultará em um erro de tempo de execução. A opção tsconfig verbatimModuleSyntax pode ser usada para corresponder a esse comportamento.

Este exemplo funcionará corretamente:

import type { Type1, Type2 } from './module.ts'
import { fn, type FnParams } from './fn.ts'

Isso resultará em um erro de tempo de execução:

import { Type1, Type2 } from './module.ts'
import { fn, FnParams } from './fn.ts'

Formas de entrada não-arquivo

A remoção de tipos pode ser habilitada para --eval. O sistema de módulos será determinado por --input-type, como é para JavaScript.

A sintaxe do TypeScript não é suportada no REPL, entrada STDIN, --print, --check e inspect.

Mapas de origem

Como os tipos embutidos são substituídos por espaços em branco, os mapas de origem são desnecessários para números de linha corretos em rastros de pilha; e o Node.js não os gera. Quando --experimental-transform-types está habilitado, os mapas de origem são habilitados por padrão.

Remoção de tipos em dependências

Para desencorajar os autores de pacotes de publicar pacotes escritos em TypeScript, o Node.js, por padrão, se recusará a lidar com arquivos TypeScript dentro de pastas em um caminho node_modules.

Aliases de caminhos

tsconfig "paths" não será transformado e, portanto, produzirá um erro. O recurso mais próximo disponível são as importações de subcaminho com a limitação de que precisam começar com #.