Mejores prácticas para módulos

Los límites de los módulos dan forma a la capacidad de despliegue y a las refactorizaciones. Estandariza en ESM, exports explícitas y dependencias package.json honestas, a menos que un ADR documente una excepción de módulo dual.

Cómo usar esta lista

• Aplícala a cada nuevo paquete en un monorepo y a cada librería publicable.
• Durante la migración de CJS, verifica solo los elementos marcados como relevantes; no publiques en modo dual sin una fecha de finalización.
• Combínala con Knip o dependency-cruiser en CI para la detección de dependencias fantasma.
• Revísala cuando TypeScript o Node cambien los valores predeterminados de resolución de módulos.

A - Elección del sistema de módulos

• Establece "type": "module" en los nuevos paquetes de aplicación. CJS solo para configuraciones .cjs y shims heredados.
• Un sistema de módulos por paquete desplegable cuando sea posible. CJS/ESM dual solo para librerías publicadas con pruebas de interoperabilidad documentadas.
• Usa las extensiones .mjs / .cjs cuando mezcles sistemas en un paquete. Nunca confíes en el análisis ambiguo de .js.
• Documenta las excepciones de módulo dual en un ADR con fecha de finalización. El modo dual es migración, no arquitectura.
• Prefiere el prefijo node: en las importaciones integradas. Evita el sombreado y aclara la intención.

B - Higiene de package.json

• Define "exports" para librerías y paquetes de monorepo compartidos. Bloquea las importaciones profundas en src/.
• Declara cada importación de especificador simple en dependencies. No confíes en dependencias fantasma elevadas.
• Apuntan las exports a dist/ compilado, no al código fuente de TypeScript. Los consumidores ejecutan JS que coincide con la resolución de Node.
• Exporta "./package.json" solo cuando las herramientas lo requieran. Mantén la superficie mínima de lo contrario.
• Usa el protocolo de espacio de trabajo (workspace:*) de forma consistente en monorepos. Bloquea las versiones al publicar.

C - Estilo de importación

• Prefiere las exportaciones con nombre sobre las predeterminadas para las librerías. Mejores refactorizaciones y claridad en el tree shaking.
• Usa import type para importaciones solo de tipo. Habilita verbatimModuleSyntax y paquetes más limpios.
• Incluye extensiones .js en las rutas de importación relativas de ESM. Coincide con la emisión y el tiempo de ejecución de NodeNext.
• Limita import() dinámico a plugins y rutas de código opcionales. Mantén el grafo central estático y analizable.
• Evita las dependencias circulares entre archivos barril. Importa directamente desde los módulos hoja.

D - Alineación de TypeScript

• Usa "module": "NodeNext" y "moduleResolution": "NodeNext". Coincide con el resolvedor ESM de Node 24.
• No asumas que las rutas de tsconfig solucionan el tiempo de ejecución. Emite rutas correctas o usa herramientas de compilación.
• Habilita verbatimModuleSyntax para nuevos proyectos. Separa explícitamente las importaciones de tipo.
• Prueba node dist/main.js en CI, no solo tsx src. Detecta errores de extensión y exportaciones.
• Envía .d.ts junto al JS emitido con la condición de tipos exports coincidente.

E - Monorepo y publicación

• Ejecuta npm pack --dry-run antes de publicar. Verifica que files y exports incluyan solo los artefactos previstos.
• Prueba de integración tanto import como require si publicas en modo dual. Evita regresiones de peligros de paquetes duales.
• Fija las dependencias internas del espacio de trabajo a versiones compatibles en el lanzamiento. Evita suposiciones solo de symlink en los tarballs de producción.
• Usa mapas de importación #internal para módulos privados del paquete. Nunca expongas rutas # a través de exports.
• Busca ERR_PACKAGE_PATH_NOT_EXPORTED en las aplicaciones de los consumidores después de ajustar las exportaciones. Comunica los cambios importantes.

Preguntas frecuentes

Relacionado

• package.json type & exports - configuración de exportaciones
• Algoritmo de resolución de módulos - cómo Node resuelve las importaciones
• Interoperabilidad CJS ↔ ESM - puentes de migración
• Conceptos básicos de TypeScript en Node - valores predeterminados de tsconfig

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.