Executando Scripts TypeScript

Diferentes maneiras de executar arquivos TypeScript sem uma etapa manual de compilação - tsx, ts-node, o stripping de tipos nativo do Node 22 e o pipeline tradicional tsc + node.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Opção moderna mais rápida - tsx (esbuild por baixo dos panos)
npx tsx script.ts
 
# Modo de observação com tsx
npx tsx watch script.ts
 
# Opção clássica - ts-node
npx ts-node script.ts
 
# Stripping de tipos nativo do Node.js (Node 22.6+)
node --experimental-strip-types script.ts
 
# Compilar e depois executar (melhor para produção)
npx tsc
node dist/script.js

// package.json
{
  "name": "ts-cli",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/script.ts",
    "start": "tsx src/script.ts",
    "build": "tsc",
    "start:prod": "node dist/script.js"
  },
  "devDependencies": {
    "tsx": "^4.19.0",
    "typescript": "^5.6.0",
    "@types/node": "^22.0.0"
  }
}

// tsconfig.json - configuração mínima de script Node.js
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "lib": ["ES2022"],
    "types": ["node"]
  },
  "include": ["src/**/*.ts"]
}

Quando usar isso: Qualquer script onde você queira argv tipado, configuração tipada, modelos de dados tipados ou tipos compartilhados com o código da sua aplicação.

Exemplo de Trabalho

Um CLI tipado que lê um arquivo JSON e imprime um resumo.

// src/summarize.ts
#!/usr/bin/env tsx
import { readFile } from 'node:fs/promises';
import { parseArgs } from 'node:util';
 
interface Order {
  id: string;
  total: number;
  status: 'paid' | 'pending' | 'failed';
}
 
interface Summary {
  count: number;
  revenue: number;
  paid: number;
}
 
const { values, positionals } = parseArgs({
  options: {
    verbose: { type: 'boolean', short: 'v' },
  },
  allowPositionals: true,
});
 
const file = positionals[0];
if (!file) {
  console.error('Usage: summarize <orders.json> [--verbose]');
  process.exit(1);
}
 
const raw = await readFile(file, 'utf8');
const orders = JSON.parse(raw) as Order[];
 
const summary: Summary = orders.reduce<Summary>(
  (acc, o) => ({
    count: acc.count + 1,
    revenue: acc.revenue + o.total,
    paid: acc.paid + (o.status === 'paid' ? 1 : 0),
  }),
  { count: 0, revenue: 0, paid: 0 },
);
 
if (values.verbose) {
  console.log(JSON.stringify(summary, null, 2));
} else {
  console.log(`orders=${summary.count} revenue=${summary.revenue} paid=${summary.paid}`);
}

# Execute-o
npx tsx src/summarize.ts ./orders.json --verbose

O que isso demonstra:

• Tipos interface tanto para os dados de entrada quanto para o resultado computado
• reduce tipado com um argumento genérico explícito
• await de nível superior em um arquivo TypeScript ESM
• Shebang apontando para tsx para que o script seja executado diretamente quando executável
• Análise de argv sem dependências com node:util

Mergulho Profundo

Como Funciona

Nenhum dos "runners TypeScript" faz type-checking em tempo de execução. Todos eles removem tipos e entregam o JavaScript resultante para o motor V8. As diferenças estão em como - e quão rápido - essa remoção acontece.

• tsx usa esbuild. A inicialização é ~10x mais rápida que ts-node e ele suporta ESM, JSX e modo de observação prontos para uso.
• ts-node usa o compilador real do TypeScript. Mais lento para iniciar, mas a emissão de tipos mais fiel (por exemplo, inlining completo de const enum, metadados de decorador).
• --experimental-strip-types é o loader embutido do Node.js (flag estável no Node 22.6+, sem flag no Node 23+). Ele deleta anotações de tipo através de uma transformação leve - ele não compila enums ou namespaces, e não faz type-checking.
• tsc + node emite arquivos JavaScript reais em outDir. É isso que você envia para produção porque elimina completamente a dependência do runner em tempo de execução.

Como nenhum desses runners faz type-checking, emparelhe-os com tsc --noEmit em CI ou em um hook de pré-commit para garantir a segurança de tipos.

Variações

# tsx vs ts-node - flags diferentes, formato similar
npx tsx script.ts --flag
npx ts-node script.ts --flag
 
# tsx com modo de observação e um glob
npx tsx watch --clear-screen=false src/**/*.ts
 
# Stripping de tipos nativo do Node.js
node --experimental-strip-types script.ts
 
# Compilar e executar para imagens Docker de produção
tsc && node dist/script.js
 
# Executar tsx via shebang
# #!/usr/bin/env -S npx tsx

// tsconfig.json mais rigoroso para scripts
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "exactOptionalPropertyTypes": true,
    "forceConsistentCasingInFileNames": true,
    "verbatimModuleSyntax": true,
    "types": ["node"]
  }
}

Notas TypeScript

Para scripts Node.js, as opções de compilador mais importantes são:

• "target": "ES2022" - Node 18+ o suporta nativamente, então sem polyfills.
• "module": "NodeNext" - corresponde à resolução de módulos real do Node, respeita "type" do package.json e força extensões .js nas importações.
• "moduleResolution": "NodeNext" - o único modo de resolução que modela com precisão a lógica de pacotes duplos do Node.
• "outDir": "dist" - onde tsc coloca o JavaScript compilado.
• "types": ["node"] - inclui globais do @types/node como process, Buffer e __dirname (apenas CJS).

Com NodeNext, especificadores de importação devem incluir a extensão .js final mesmo que você esteja escrevendo .ts. Isso parece estranho na primeira vez:

import { loadOrders } from './orders.js'; // refere-se a orders.ts

Armadilhas

1. Misturando ESM e CJS. Se "type": "module" estiver definido, arquivos .ts compilam para ESM e require lançará um erro. Se precisar de require, use createRequire(import.meta.url) ou renomeie para .cts.
2. ts-node inicialização lenta. O compilador TypeScript completo pode adicionar 1–3 segundos por execução. Para scripts iterativos, use tsx em vez disso - seu pipeline baseado em esbuild geralmente inicia em menos de 100 ms.
3. __dirname em TypeScript ESM. Ele só é definido em CJS. Em ESM, reconstrua-o: const __dirname = path.dirname(fileURLToPath(import.meta.url)).
4. Importando sem extensão .js. Com "module": "NodeNext" você deve escrever ./foo.js, não ./foo. O runner vê o arquivo .ts; o compilador TypeScript valida que o destino existe.
5. Assumindo que o runner faz type-checking. tsx, ts-node --transpile-only e --experimental-strip-types todos pulam o type-checking por padrão. Execute tsc --noEmit em CI.
6. Limitações do --experimental-strip-types. Ele se recusa a lidar com sintaxe de enum, namespace e propriedade de parâmetro. Use objetos const ou tsx se precisar desses recursos.
7. Esquecendo @types/node. Sem ele, process, Buffer e todo o namespace de módulo node:* aparecem como any, derrotando o modo estrito.

Alternativas

FAQs

import { fileURLToPath } from 'node:url';
import { dirname } from 'node:path';
const __dirname = dirname(fileURLToPath(import.meta.url));

Relacionados

• Executando Scripts Node.js em JavaScript
• Módulos ESM vs CommonJS
• Noções Básicas de TypeScript
• Configuração do ESLint