Conceptos básicos de los módulos

8 ejemplos para empezar con los módulos: 6 básicos y 2 intermedios.

Prerrequisitos

• Node.js 24.18.0 con "type": "module" en package.json para los ejemplos de ESM.
• Comprender la estructura del proyecto Conceptos básicos de Node.js.
• ¿Eres nuevo en CJS vs. ESM? Empieza con Tipos de módulos de Node.js para el modelo conceptual sobre el que se construyen estos ejemplos.

Ejemplos básicos

1. Exportación e importación de ESM

Las exportaciones con nombre son analizables estáticamente, el valor predeterminado preferido en 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));

• Usa extensiones .js en los especificadores de importación al compilar TypeScript a ESM.
• import type se borra en tiempo de compilación, sin costo en tiempo de ejecución.
• ESM permite el tree shaking en los empaquetadores y APIs públicas explícitas.

Relacionado: Módulos ES (import) - importación dinámica y TLA

2. Exportación predeterminada (con moderación)

Una exportación predeterminada por módulo: úsala para puntos de entrada de un solo propósito.

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

• Prefiere las exportaciones con nombre para las bibliotecas: mejor refactorización y autocompletado.
• Las exportaciones predeterminadas complican las reexportaciones en los archivos barrel.
• Las configuraciones de los frameworks a menudo usan exportaciones predeterminadas por convención.

3. CommonJS require (Legado)

El código brownfield todavía usa require: conócelo para el mantenimiento.

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

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

• La extensión .cjs fuerza CommonJS incluso cuando "type": "module".
• require es síncrono: no hay await de nivel superior en los módulos CJS.
• Migra los archivos hoja a ESM antes que los manejadores de rutas.

Relacionado: CommonJS (require) - patrones de module.exports

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

Establece ESM como predeterminado para los archivos .js en el paquete.

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

• Sin "type": "module", los archivos .js se tratan como CommonJS.
• "type": "commonjs" es el modo heredado explícito.
• Las bibliotecas publicadas documentan "exports" para los puntos de entrada públicos.

Relacionado: package.json type y exports - exportaciones condicionales

5. Prefijo node: incorporado

Aclara las importaciones incorporadas y evita el sombreado de paquetes de usuario.

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

• El prefijo node: es opcional pero recomendado en el código de la aplicación.
• Evita que un paquete fs local secuestre las importaciones.
• Funciona tanto en ESM como en CJS (require('node:fs')).

6. import() dinámico

Carga módulos condicionalmente o en tiempo de ejecución: devuelve una Promesa.

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

• Los especificadores dinámicos deben permanecer dentro de los límites analizables para los empaquetadores.
• Útil para características opcionales y división de código.
• No puede reemplazar las importaciones estáticas para rutas críticas de tree-shaking.

Relacionado: Módulos ES (import) - await de nivel superior con importación dinámica

Ejemplos intermedios

7. Archivo Barrel (API pública)

Reexporta una superficie curada desde 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';

• Los archivos barrel simplifican las importaciones, pero pueden ralentizar el IDE y los empaquetadores si son enormes.
• Exporta solo tipos públicos: oculta los módulos internos.
• Evita los barrels circulares: divide los dominios en su lugar.

Relacionado: Algoritmo de resolución de módulos - cómo se resuelve el índice

8. Interoperabilidad CJS ↔ ESM en un solo repositorio

Módulos mixtos durante la migración: extensiones explícitas y 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 carga CJS desde el contexto ESM durante la migración brownfield.
• Planifica una fecha de caducidad de ADR para paquetes de doble módulo.
• Prueba las rutas import y require en CI durante la transición.

Relacionado: Interoperabilidad CJS ↔ ESM - paquetes duales y .mjs/.cjs

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