TypeScript no Node: Noções Básicas

8 exemplos para você começar com TypeScript no Node - 6 básicos e 2 intermediários.

Pré-requisitos

• Node.js 24.18.0, TypeScript 5.6+, npm install -D typescript tsx @types/node.
• "type": "module" em package.json para os exemplos ESM abaixo.

Exemplos Básicos

1. tsconfig Mínimo para Node 24 ESM

NodeNext alinha o TypeScript com o resolvedor de módulos do Node.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

• strict habilita strictNullChecks, noImplicitAny e outras flags relacionadas juntas.
• skipLibCheck acelera as compilações - ainda assim, verifique os tipos do seu src.
• outDir/rootDir mantêm dist/ espelhando src/.

Relacionado: tsx vs tsc vs ts-node - pipelines de desenvolvimento vs produção

2. process.env Tipado (Padrão Inseguro)

Valores de process.env são string | undefined - restrinja antes de usar.

const port = Number(process.env.PORT ?? 3000);
if (Number.isNaN(port)) throw new Error('PORT inválido');

• Variáveis de ambiente são sempre strings quando presentes.
• ?? lida com undefined; string vazia requer tratamento explícito.
• Valide variáveis obrigatórias na inicialização - veja o exemplo Zod em Zod nas Fronteiras.

3. Importe Built-ins com Tipos

@types/node vem com tipagens de qualidade DefinitelyTyped para APIs do Node 24.

import { readFile } from 'node:fs/promises';
import type { Stats } from 'node:fs';
 
const stat: Stats = await readFile('package.json').then(() => import('node:fs')).then(fs => fs.promises.stat('package.json'));

• Use import type para importações apenas de tipos com verbatimModuleSyntax.
• A versão de @types/node deve corresponder à sua versão principal do Node (npm i -D @types/node@24).
• Prefira o prefixo node: no código da aplicação.

4. Caminhos de Importação ESM com Extensão .js

O TypeScript em código-fonte importa .js porque a emissão mantém os especificadores inalterados.

// src/user.ts
export interface User { id: string; name: string }

// src/main.ts
import { type User } from './user.js';

• Isso parece estranho em arquivos .ts, mas corresponde à resolução do runtime ESM do Node.
• moduleResolution: NodeNext impõe esse padrão.
• Bundlers podem reescrever extensões - aplicativos Node sem bundle não podem.

Relacionado: Módulos ESM (import) - Regras ESM

5. Tipo de Retorno do Handler async

Handlers do Express/Fastify devem retornar void ou Promise<void> explicitamente.

import type { Request, Response } from 'express';
 
export async function getHealth(_req: Request, res: Response): Promise<void> {
  res.json({ status: 'ok' });
}

• Handlers assíncronos retornam Promises - garanta que os erros se propaguem para o middleware de erro.
• Use tipos específicos do framework para aprimoramento de requisições - veja Tipando Handlers do Express/Fastify.
• Evite any em req e res - defina genéricos para body e params.

6. node:test com TypeScript

Testes nativos com tipos - nenhum Jest é necessário para testes unitários.

import { test } from 'node:test';
import assert from 'node:assert/strict';
 
function slugify(input: string): string {
  return input.toLowerCase().replace(/\s+/g, '-');
}
 
test('slugify', () => {
  assert.equal(slugify('Hello World'), 'hello-world');
});

node --import tsx --test src/**/*.test.ts

• Coloque *.test.ts ao lado do código-fonte ou sob src/__tests__.
• assert/strict lança erros na falha com diffs claros.
• CI pode executar dist/**/*.test.js compilado após tsc para paridade.

Exemplos Intermediários

7. Restrição de null estrita

strictNullChecks força o tratamento de null e undefined.

function findUser(id: string, users: Map<string, { name: string }>): string {
  const user = users.get(id);
  if (!user) throw new Error(`Usuário ${id} não encontrado`);
  return user.name;
}

• O encadeamento opcional user?.name retorna string | undefined - ainda restrinja para a lógica de negócios.
• Evite a asserção de não-nulo ! exceto em testes ou após guards explícitos.
• Camadas de banco de dados que retornam null devem mapear para tipos Result ou exceções nas fronteiras.

Relacionado: Zod nas Fronteiras - validação em tempo de execução

8. Pacote de tipos compartilhado (Monorepo)

Publique DTOs de tipos sem segredos do servidor.

// packages/types/src/user.ts
export interface UserDto {
  id: string;
  displayName: string;
}

// apps/api/src/handlers/user.ts
import type { UserDto } from '@acme/types/user';
 
export function toDto(user: { id: string; name: string }): UserDto {
  return { id: user.id, displayName: user.name };
}

• Exporte módulos apenas de tipos - sem segredos do servidor no pacote compartilhado.
• Use exports em @acme/types/package.json para subcaminhos.
• Veja Compartilhando Tipos com o Frontend para padrões completos de monorepo.

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.