Noções Básicas de Módulos

8 exemplos para você começar com Módulos - 6 básicos e 2 intermediários.

Pré-requisitos

• Node.js 24.18.0 com "type": "module" em package.json para exemplos ESM.
• Entenda o layout do projeto Noções Básicas de Node.js.
• Novo em CJS vs. ESM? Comece com Tipos de Módulo do Node.js para o modelo conceitual em que estes exemplos se baseiam.

Exemplos Básicos

1. Exportação e Importação ESM

Exportações nomeadas são analisáveis estaticamente - o padrão preferido em 2026.

// user.ts
export interface User { id: string; name: string }
export function formatUser(u: User): string {
  return `${u.name} (${u.id})`;
}

// main.ts
import { formatUser, type User } from './user.js';
 
const user: User = { id: '1', name: 'Ada' };
console.log(formatUser(user));

• Use extensões .js em especificadores de importação ao compilar TypeScript para ESM.
• import type é removido em tempo de compilação - sem custo de tempo de execução.
• ESM permite tree shaking em bundlers e APIs públicas explícitas.

Relacionado: Módulos ESM (import) - importação dinâmica e TLA

2. Exportação Padrão (Com Moderação)

Uma exportação padrão por módulo - use para pontos de entrada de propósito único.

// logger.ts
export default function createLogger(prefix: string) {
  return (msg: string) => console.log(`[${prefix}]`, msg);
}

import createLogger from './logger.js';
const log = createLogger('api');
log('started');

• Prefira exportações nomeadas para bibliotecas - melhor refatoração e autocompletar.
• Exportações padrão complicam re-exportações em arquivos "barrel".
• Configurações de frameworks frequentemente usam exportações padrão por convenção.

3. require do CommonJS (Legado)

Código "brownfield" ainda usa require - conheça para manutenção.

// legacy.cjs
const path = require('node:path');
module.exports = {
  basename: (p) => path.basename(p),
};

const { basename } = require('./legacy.cjs');

• A extensão .cjs força CommonJS mesmo quando "type": "module".
• require é síncrono - sem top-level await em módulos CJS.
• Migre arquivos "leaf" para ESM antes dos manipuladores de rota.

Relacionado: CommonJS (require) - padrões de module.exports

4. "type": "module" no package.json

Define ESM como padrão para arquivos .js no pacote.

{
  "name": "billing-api",
  "type": "module",
  "exports": {
    ".": "./dist/index.js"
  }
}

• Sem "type": "module", arquivos .js são tratados como CommonJS.
• "type": "commonjs" é o modo legado explícito.
• Bibliotecas publicadas documentam "exports" para pontos de entrada públicos.

Relacionado: type & exports do package.json - exportações condicionais

5. Prefixo node: Embutido

Clarifica importações embutidas e evita sombreamento de pacotes do usuário.

import { readFile } from 'node:fs/promises';
import { createServer } from 'node:http';

• O prefixo node: é opcional, mas recomendado em código de aplicação.
• Impede que um pacote local fs sequestre importações.
• Funciona tanto em ESM quanto em CJS (require('node:fs')).

6. import() dinâmico

Carrega módulos condicionalmente ou em tempo de execução - retorna uma Promise.

async function loadPlugin(name: string) {
  const mod = await import(`./plugins/${name}.js`);
  return mod.default();
}
 
await loadPlugin('metrics');

• Especificadores dinâmicos devem permanecer dentro de limites analisáveis para bundlers.
• Útil para recursos opcionais e divisão de código.
• Não pode substituir importações estáticas para tree-shaking de caminhos críticos.

Relacionado: Módulos ESM (import) - top-level await com importação dinâmica

Exemplos Intermediários

7. Arquivo Barrel (API Pública)

Re-exporta uma superfície curada de index.ts.

// src/services/index.ts
export { UserService } from './user-service.js';
export type { User } from './user-service.js';

import { UserService, type User } from './services/index.js';

• Arquivos barrel simplificam importações, mas podem desacelerar IDEs e bundlers se forem enormes.
• Exporte apenas tipos públicos - oculte módulos internos.
• Evite barrels circulares - divida domínios em vez disso.

Relacionado: Algoritmo de Resolução de Módulos - como index resolve

8. Interoperabilidade CJS ↔ ESM em Um Repositório

Módulos mistos durante a migração - extensões explícitas e createRequire.

// bridge.mjs
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const legacy = require('./legacy-config.cjs');
console.log(legacy.apiUrl);

• createRequire carrega CJS do contexto ESM durante a migração "brownfield".
• Planeje uma data de encerramento para pacotes de módulo duplo.
• Teste os caminhos import e require em CI durante a transição.

Relacionado: Interoperabilidade CJS ↔ ESM - pacotes duplos e .mjs/.cjs

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.