Módulos ES (import)

Los Módulos ES son el sistema de módulos estándar de JavaScript: import/export estáticos, import() dinámico y await de nivel superior brindan a los servicios de Node 24 gráficos de dependencia explícitos e inicialización asíncrona.

Receta

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');

Cuándo usarlo:

• Todos los nuevos servicios de backend de Node 24 ("type": "module")
• Librerías que publican APIs públicas tipadas
• Carga condicional de plugins en tiempo de ejecución
• Configuración de arranque antes de escuchar en un puerto (await de nivel superior)

Ejemplo de trabajo

// config.ts - el await de nivel superior carga antes de que el 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();

Lo que esto demuestra:

• El await de nivel superior bloquea a los importadores hasta que config esté listo, sin un wrapper async main manual
• import.meta.url resuelve rutas relativas en ESM sin __dirname
• import() dinámico permite la selección de plugins desde variables de entorno
• Las importaciones estáticas se elevan: se ejecutan antes del cuerpo del módulo pero después de la carga del gráfico de dependencias

Inmersión profunda

Cómo funciona

• Las importaciones estáticas se analizan antes de la ejecución; las dependencias circulares de ESM fallan rápidamente con errores más claros que CJS.
• Enlaces en vivo - las importaciones con nombre son referencias a enlaces exportados, no copias (para exportaciones let/const).
• import() dinámico devuelve Promise<Module> - funciona en CJS a través de un wrapper asíncrono y en ESM en cualquier lugar.
• Atributos de importación (experimental/estable según la versión) controlan los tipos de módulos JSON/CSS - consulta la documentación de Node 24 para with { type: 'json' }.

Formas de importación

Notas de TypeScript

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

Usa NodeNext para que TypeScript aplique las extensiones .js que coinciden con la resolución de Node.

Errores comunes

• Falta la extensión .js en las rutas de importación - ERR_MODULE_NOT_FOUND en tiempo de ejecución después de tsc. Solución: moduleResolution: NodeNext e import './file.js'.
• El await de nivel superior bloquea el inicio de toda la aplicación - la importación lenta de la configuración retrasa todas las rutas. Solución: importación dinámica perezosa para módulos opcionales pesados.
• Importación dinámica con rutas totalmente variables - los bundlers y los escáneres de seguridad no pueden analizar. Solución: lista blanca de nombres de plugins.
• Mezclar importación predeterminada y con nombre incorrectamente - import fs from 'node:fs' falla sin exportación predeterminada. Solución: import * as fs from 'node:fs' o importaciones con nombre.
• ESM circular entre archivos barril - errores TDZ en enlaces no inicializados. Solución: importar desde módulos hoja, no barriles cíclicos.

Alternativas

Preguntas frecuentes

Relacionado

• package.json type & exports - resolución de entrada de paquetes
• Interoperabilidad CJS ↔ ESM - gráficos de módulos mixtos
• Algoritmo de resolución de módulos - cómo se resuelven los especificadores
• Conceptos básicos de TypeScript en Node - tsconfig para ESM

Versiones de stack: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.