Módulos ES (import)

Módulos ES são o sistema de módulos padrão do JavaScript - import/export estáticos, import() dinâmico e await de nível superior dão aos serviços Node 24 grafos de dependência explícitos e inicialização assíncrona.

Receita

import { readFile } from 'node:fs/promises';
import type { Server } from 'node:http';
 
export async function loadConfig(path: string): Promise<Record<string, string>> {
  const raw = await readFile(path, 'utf8');
  return JSON.parse(raw) as Record<string, string>;
}

const mod = await import('./feature.js');

Quando usar isso:

• Todos os novos serviços de backend Node 24 ("type": "module")
• Bibliotecas que publicam APIs públicas tipadas
• Carregamento condicional de plugins em tempo de execução
• Inicialização de configuração antes de escutar em uma porta (await de nível superior)

Exemplo de Trabalho

// config.ts - await de nível superior carrega antes que o servidor importe este módulo
import { readFile } from 'node:fs/promises';
 
export const config = JSON.parse(
  await readFile(new URL('./config.json', import.meta.url), 'utf8'),
) as { port: number; host: string };

// server.ts
import { createServer } from 'node:http';
import { config } from './config.js';
 
const server = createServer((req, res) => {
  res.end(`listening config port ${config.port}`);
});
 
server.listen(config.port, config.host);

// plugins/loader.ts
const pluginName = process.env.PLUGIN ?? 'default';
const plugin = await import(`./${pluginName}.js`);
await plugin.register();

O que isso demonstra:

• await de nível superior bloqueia os importadores até que config esteja pronto - sem wrapper main manual assíncrono
• import.meta.url resolve caminhos relativos em ESM sem __dirname
• import() dinâmico permite a seleção de plugins a partir de variáveis de ambiente
• Imports estáticos são içados (hoisted) - eles rodam antes do corpo do módulo, mas depois do carregamento do grafo de dependência

Mergulho Profundo

Como Funciona

• Imports estáticos são analisados antes da execução - dependências ESM circulares falham rapidamente com erros mais claros que CJS.
• Vínculos dinâmicos (Live bindings) - imports nomeados são referências a vínculos exportados, não cópias (para exports let/const).
• Importação dinâmica import() retorna Promise<Module> - funciona em CJS via wrapper assíncrono e em ESM em qualquer lugar.
• Atributos de importação (experimentais/estáveis dependendo da versão) controlam tipos de módulo JSON/CSS - verifique a documentação do Node 24 para with { type: 'json' }.

Formas de Importação

Notas do TypeScript

// tsconfig.json para Node 24 ESM
{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2022",
    "verbatimModuleSyntax": true
  }
}

Use NodeNext para que o TypeScript imponha extensões .js correspondentes à resolução do Node.

Armadilhas

• Extensão .js ausente nos caminhos de importação - ERR_MODULE_NOT_FOUND em tempo de execução após tsc. Correção: moduleResolution: NodeNext e import './file.js'.
• Await de nível superior bloqueando a inicialização completa do aplicativo - importação lenta de configuração atrasa todas as rotas. Correção: importação dinâmica preguiçosa para módulos opcionais pesados.
• Importação dinâmica com caminhos totalmente variáveis - bundlers e scanners de segurança não conseguem analisar. Correção: liste nomes de plugins permitidos.
• Mistura incorreta de importação padrão e nomeada - import fs from 'node:fs' falha sem exportação padrão. Correção: import * as fs from 'node:fs' ou imports nomeados.
• ESM circular entre arquivos de barril (barrel files) - erros TDZ em vínculos não inicializados. Correção: importe de módulos folha, não de barris cíclicos.

Alternativas

FAQs

Relacionados

• Tipo e exports do package.json - resolução de entrada de pacote
• Interop CJS ↔ ESM - grafos de módulos mistos
• Algoritmo de Resolução de Módulos - como os especificadores são resolvidos
• Básico de TypeScript no Node - tsconfig para ESM

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.