Al cerrar la lección anterior el modelo de Nómada Tareas estaba completo y protegido: Tarea con su estado privado, Tablero con su API pública mínima, ErrorDeValidacion con su jerarquía. El problema es que todo eso vive en un único js/app.js que ya pasa de las trescientas líneas, mezclado con las constantes, el backlog de ejemplo y el código que lo ejecuta. Partirlo en varios ficheros y cargarlos con <script> no soluciona nada: todos comparten el mismo espacio global, el orden de carga se convierte en una dependencia invisible que nadie ha escrito, y basta que dos ficheros declaren const PESOS para que la aplicación se caiga. En esta lección aprenderás el sistema de módulos de JavaScript: fronteras explícitas entre ficheros, con export para declarar qué se ofrece e import para declarar qué se necesita. Al final habrás reorganizado el proyecto entero en seis ficheros reales, con un grafo de dependencias que se puede dibujar.

1. El problema: ámbito global, orden y dependencias invisibles
2. export: exportaciones con nombre
3. import: traer lo que necesitas
4. Renombrar con as e importar todo con * as
5. export default
6. Reexportar: el fichero de barril
7. Ámbito propio y ejecución única
8. <script type="module"> y qué cambia
9. import() dinámico y await a nivel de módulo
10. CommonJS: require y module.exports
11. Node y "type": "module"
12. Dependencias circulares
13. Nómada Tareas, reorganizado
14. Errores Comunes y Consejos
15. Ejercicios
16. Conclusión

Supongamos que partes el fichero grande en tres y los cargas como aprendiste en el Módulo 1:

Esto tiene tres problemas serios, y ninguno da un mensaje de error claro.

Problema 1: todo comparte el mismo ámbito global. Cada <script> clásico ejecuta su código en el ámbito global, así que todas las declaraciones de nivel superior conviven en el mismo espacio de nombres.

Dos ficheros escritos por dos personas distintas, cada uno perfectamente razonable, y la aplicación no arranca. Con var sería aún peor: no habría error, el segundo pisaría al primero en silencio y el cálculo del esfuerzo daría NaN en algún sitio inesperado.

Problema 2: el orden importa y no está escrito en ninguna parte. Si alguien mueve el <script> de tarea.js por encima del de constantes.js, la clase Tarea intentará usar PESOS antes de que exista. El HTML se convierte en un fichero de configuración crítico que nadie documenta.

Problema 3: las dependencias son invisibles. Abre tarea.js y dime de qué depende. No puedes saberlo sin leerlo entero y buscar los identificadores que no declara. No hay ninguna línea que diga «este fichero necesita PESOS y ErrorDeValidacion».

El apaño clásico, antes de que existieran los módulos, era el patrón módulo de 03-04: encerrarlo todo en una función que se invoca a sí misma y colgar del global una sola variable.

Funciona —era la mejor práctica durante años— pero sigue sin resolver el orden ni hacer explícitas las dependencias, y basta que dos librerías elijan el mismo nombre global para volver al problema 1. Desde ES2015, el lenguaje trae la solución de serie.

Un módulo es simplemente un fichero .js que usa export o import. Todo lo que declara es privado a ese fichero salvo lo que exporta explícitamente.

Hay dos formas de escribir lo mismo. La primera es poner export delante de cada declaración, como arriba. La segunda es agrupar al final del fichero, lo que da una «tabla de contenidos» muy cómoda de leer:

Se puede exportar cualquier cosa con nombre: const, let, function, class. Y se puede renombrar en la propia exportación:

Las declaraciones export e import deben estar en el nivel superior del módulo, nunca dentro de un if, un bucle o una función. El motivo es que se analizan antes de ejecutar nada: eso permite al navegador descubrir el grafo de ficheros y descargarlos en paralelo, y es también lo que hace posible detectar errores de importación sin llegar a ejecutar el programa. Para importar condicionalmente existe import() dinámico (apartado 9).

En el otro extremo, import declara qué se necesita y de dónde viene.

Las llaves de import { … } no son desestructuración, aunque se parezcan mucho a la de 04-07. Es una sintaxis propia del sistema de módulos: los nombres tienen que coincidir exactamente con los exportados, no admite valores por defecto ni patrones anidados, y se resuelve antes de ejecutar.

Sobre la ruta del módulo (el especificador), tres reglas que causan muchos tropiezos en el navegador:

Y la más importante: en el navegador, la extensión .js es obligatoria. import { HOY } from './util/fechas' falla con un 404. Node en modo ESM también la exige. Es el error número uno de quien viene de otros entornos donde se puede omitir.

Si dos módulos exportan algo con el mismo nombre, o si el nombre original choca con una variable local, se renombra al importar:

Y si quieres todo el módulo agrupado bajo un nombre:

Ese fechas es el objeto de espacio de nombres del módulo: contiene una propiedad por cada exportación. Tiene dos particularidades: está congelado (no puedes añadirle ni cambiarle nada) y sus propiedades son enlaces vivos, no copias, algo que verás en el apartado 7.

Cada módulo puede tener una exportación por defecto, pensada para cuando el fichero representa una sola cosa.

La diferencia con las exportaciones con nombre:

Se pueden combinar en el mismo fichero:

En este proyecto usaremos exportaciones con nombre en todos los ficheros. No es la única opción válida —muchos equipos usan default para la pieza principal de cada módulo—, pero las nombradas tienen dos ventajas prácticas: el nombre es el mismo en todo el código base, lo que hace que buscar Tablero encuentre todos los usos, y un error de tecleo salta al instante en lugar de dar undefined a mitad de la ejecución.

Un módulo puede reexportar lo que importa de otros, sin llegar a usarlo. Sirve para ofrecer un punto de entrada único a un grupo de ficheros.

Quien lo consume ve un único módulo:

Los barriles son cómodos, pero conviene una advertencia honesta: al importar del barril arrastras la carga de todos los ficheros que reexporta, aunque solo uses uno. Con seis ficheros es irrelevante; en proyectos grandes es una de las causas típicas de que el arranque se vuelva lento, y su relación con la división de código se trata en 09-05. Para un proyecto del tamaño de Nómada Tareas, importar directamente de cada fichero es más claro.

Dos propiedades de los módulos que resuelven exactamente los problemas del apartado 1.

Cada módulo tiene su propio ámbito. Nada de lo que declaras es global, así que dos módulos pueden declarar const PESOS sin enterarse el uno del otro. Se acabó el problema 1.

Un módulo se ejecuta una sola vez, por muchas veces que se importe. La primera importación lo carga y ejecuta; las demás reciben el resultado ya calculado. Esto convierte a cada módulo en un singleton de facto:

En consola, '⚙ contador.js se está ejecutando' aparece una sola vez. Los dos módulos comparten el mismo registro porque comparten la misma instancia del módulo. Esa propiedad es utilísima —un módulo de configuración, una caché, un almacén compartido—, pero conviene tenerla presente: el estado que pongas a nivel de módulo es global para toda la aplicación, con todos los inconvenientes que eso tiene para las pruebas del Módulo 8.

Y un detalle fino: las importaciones son enlaces vivos, no copias. Si el módulo de origen reasigna una variable exportada, quien la importó ve el valor nuevo.

Las variables importadas son de solo lectura desde el módulo que importa: solo el módulo propietario puede cambiarlas. Es una forma de encapsulación que encaja perfectamente con lo que aprendiste en 05-03.

Para que el navegador trate un fichero como módulo hay que decírselo:

Un solo <script> para toda la aplicación: los import se encargan del resto, y el navegador descubre y descarga el grafo completo. Estas son las diferencias respecto a un script clásico:

El defer implícito es una buena noticia práctica: cuando llegues al Módulo 6 y empieces a buscar elementos de la página, el HTML ya estará completamente construido, sin necesidad de esperar a ningún evento. Y si necesitas lo contrario —que se ejecute en cuanto se descargue, sin esperar—, existe <script type="module" async src="…">.

La última fila es la que más quebraderos de cabeza da. Abrir el index.html con doble clic no funciona con módulos:

El motivo es de seguridad: los módulos se descargan con las mismas reglas que cualquier petición de red, y el protocolo file:// no tiene un origen válido. La solución es la que ya conociste en 01-02: levantar un servidor local.

Y después abrir http://localhost:8000, no la ruta del fichero. A partir de ahora, todo el desarrollo del proyecto se hace con un servidor local en marcha.

Las importaciones estáticas van al principio del fichero y se resuelven antes de ejecutar. Cuando necesitas cargar algo condicionalmente o en un momento concreto, existe la forma de función:

Nos centramos aquí solo en la sintaxis, porque su uso principal —dividir la aplicación en trozos que se descargan bajo demanda para que arranque antes— es materia de 09-05, y porque lo que devuelve es una promesa, un objeto que estudiarás a fondo en 05-06. Retén tres diferencias:

Ese await del ejemplo tampoco es habitual fuera de una función: en los módulos ES está permitido usar await directamente en el nivel superior, algo que se llama top-level await.

Cuando un módulo usa await en el nivel superior, todos los módulos que lo importan esperan a que termine antes de ejecutarse. Es una herramienta cómoda, pero tiene un coste real en el arranque de la aplicación, así que conviene usarla con cabeza. Volverás sobre ella en 05-06, cuando await deje de ser una palabra que aparece de pasada.

Antes de que los módulos ES existieran, Node.js inventó su propio sistema, llamado CommonJS, y sigue siendo omnipresente. Vas a encontrarlo constantemente, así que hay que reconocerlo.

Aquí las llaves sí son desestructuración de verdad (04-07), porque require devuelve un objeto normal y corriente. Esa es la diferencia de fondo entre los dos sistemas:

La diferencia entre «enlace vivo» y «copia» tiene consecuencias visibles:

Con ESM, ese mismo código imprimiría 1. Es una fuente clásica de confusión al migrar entre sistemas.

Cuál usar hoy: ESM en todo lo nuevo. Es el estándar del lenguaje, funciona en navegador y en Node, y permite el análisis estático del que dependen las herramientas de 09-05. CommonJS lo verás en proyectos con años, en muchos ficheros de configuración y en dependencias antiguas.

En el navegador, type="module" en la etiqueta decide el sistema. En Node lo decide el package.json de la carpeta:

Con "type": "module", Node interpreta todos los .js de ese proyecto como módulos ES. Sin esa línea (o con "type": "commonjs"), los interpreta como CommonJS. Y si necesitas mezclar, las extensiones mandan sobre el package.json:

Con eso, ya puedes ejecutar el proyecto desde la terminal, algo muy cómodo para probar la lógica sin abrir el navegador:

Un aviso frecuente: en un módulo ES no existen require, __dirname ni __filename. Si los necesitas, hay equivalentes modernos, pero lo normal es no echarlos de menos.

Dos módulos que se importan mutuamente forman un ciclo. No es un error del lenguaje, pero suele acabar en undefined en el peor momento.

Lo que pasa por dentro es que un módulo empieza a ejecutarse, encuentra el import, va al otro, y ese vuelve al primero —que aún no ha terminado de ejecutarse—. Con las class, que tienen zona muerta temporal (05-02), el resultado típico es un error del tipo Cannot access 'Tarea' before initialization.

Casi siempre un ciclo es una señal de diseño: dos módulos que se necesitan mutuamente en realidad son uno, o les falta un tercero. Las tres salidas habituales:

1. Extraer lo común a un tercer módulo. Si ambos necesitan las constantes y los errores, sácalos a modelo/errores.js y modelo/reglas.js, y que los dos dependan de ellos.
2. Invertir la dependencia. Que Tablero conozca a Tarea (agrega tareas), pero que Tarea no conozca a Tablero. Si una tarea necesita algo del tablero, que se lo pasen por parámetro.
3. Fusionar los dos módulos si de verdad son inseparables.

En Nómada Tareas aplicamos la número 2, que es la que produce un grafo limpio: las capas de abajo no conocen a las de arriba.

Aquí está el proyecto entero repartido en sus módulos definitivos. Esta es la estructura sobre la que trabajarán todos los módulos siguientes del curso.

Y su grafo de dependencias:

Fíjate en que todas las flechas van hacia abajo: util/ y modelo/errores.js no dependen de nadie, modelo/tarea.js depende de ellos, modelo/tablero.js depende de la tarea, y app.js está arriba del todo. No hay ciclos, y cada fichero declara en sus primeras líneas exactamente de qué depende.

Los ficheros, ahora. Primero las hojas del grafo:

Ahora el modelo, que ya solo contiene lo que le corresponde:

Observa el import { estaVencida as fechaVencida }: la función de utilidad y el método de la clase se llaman igual, y as resuelve el choque sin renombrar ninguno de los dos. Es exactamente para esto que existe.

Ese crearBacklog() como función, en lugar de un array exportado ya construido, es una decisión deliberada. Como los módulos se ejecutan una sola vez (apartado 7), un array exportado directamente sería el mismo para toda la aplicación, y una prueba que cambiara el estado de una tarea contaminaría a la siguiente. Devolviendo instancias nuevas en cada llamada, cada consumidor tiene las suyas.

Y por fin el punto de entrada, que ya no contiene lógica: solo orquesta.

Ejecutándolo con node js/app.js (o abriendo index.html desde el servidor local y mirando la consola):

Los números canónicos de siempre, ahora producidos por seis ficheros con fronteras claras. Y lo más importante: si mañana hay que cambiar cómo se calcula el esfuerzo, sabes exactamente qué fichero abrir.

• Olvidar la extensión .js en el especificador. from './util/fechas' da un 404 en el navegador y un ERR_MODULE_NOT_FOUND en Node. La extensión es obligatoria.
• Abrir el HTML con doble clic. Los módulos no funcionan sobre file:// por CORS. Servidor local siempre.
• Confundir import { X } con desestructuración. No admite defectos, ni renombrado con :, ni patrones anidados; para renombrar se usa as.
• Nombre mal escrito en una importación con nombre. Da SyntaxError: The requested module does not provide an export named 'Tabler'. Es un buen error: aparece al cargar, no a mitad de la ejecución.
• Mezclar export default y con nombre sin criterio. Elige una convención por proyecto y respétala. En Nómada Tareas: siempre con nombre.
• Poner un import dentro de un if o de una función. Es SyntaxError; para eso está import() dinámico.
• Estado mutable a nivel de módulo. Como el módulo se ejecuta una vez, un export const cache = new Map() es global para toda la aplicación. A veces es justo lo que quieres; otras, un dolor de cabeza en las pruebas del Módulo 8. Exporta funciones fábrica cuando cada consumidor deba tener lo suyo.
• Dependencias circulares. Si ves Cannot access 'X' before initialization, busca el ciclo. La solución casi nunca es un truco: es rediseñar para que las dependencias apunten en una sola dirección.
• Barriles en proyectos grandes. Un index.js que reexporta cincuenta ficheros los carga todos aunque uses uno. Cómodo, pero con coste (09-05).
• Consejo: ordena los import de cada fichero por capas —primero librerías externas, luego módulos del proyecto, luego los más cercanos—. Es la convención que aplican las herramientas de 08-02 y hace que el fichero se lea como una declaración de intenciones.

Ejercicio 1 — Detectar el ciclo. Este proyecto no arranca. Dibuja el grafo, identifica el ciclo y propón una reorganización con un módulo nuevo.

Ejercicio 2 — Un módulo util/estadisticas.js. Crea un módulo que exporte media(numeros), maximo(objetos, campo) y agruparPor(objetos, campo), más una constante VERSION. Ninguna de las tres puede importar nada del modelo (deben servir para cualquier array de objetos). Después escribe un app.js que lo importe y calcule, sobre el backlog canónico: la media de horas de las tareas abiertas, la tarea de más horas y el agrupamiento por prioridad.

Ejercicio 3 — Contador compartido. Crea datos/metricas.js que exporte registrar(evento) y informe(), guardando el recuento en estado de módulo. Impórtalo desde modelo/tarea.js y desde modelo/tablero.js, registra un evento en cada cambio de estado y demuestra con una traza de consola que los dos módulos comparten el mismo contador. Después explica en dos líneas cuándo eso sería un problema.

Ejercicio 1

El ciclo es directo: informe.js → tablero.js → informe.js.

La causa de fondo es una inversión de capas: Tablero es una pieza del modelo y no debería saber nada de cómo se formatean los informes. La solución no es un truco de importación, sino ordenar las responsabilidades:

Grafo resultante, sin ciclos y con todas las flechas en la misma dirección:

La lección general: cuando aparece un ciclo, casi siempre hay una capa que está mirando hacia arriba. Aquí era Tablero.imprimir(), un método de presentación en una clase de modelo.

Ejercicio 2

La restricción del enunciado —que no importe nada del modelo— es el punto del ejercicio. media, maximo y agruparPor funcionan igual con tareas, con residentes o con reservas de sala, y por eso viven en util/ y no dependen de nadie: son una hoja del grafo. Un módulo de utilidades que importa del modelo deja de ser reutilizable y es la semilla del próximo ciclo. Nota además que maximo devuelve el primer máximo en caso de empate, porque la comparación es estricta (>).

Ejercicio 3

Que el informe sume las llamadas hechas desde dos módulos distintos demuestra que ambos recibieron la misma instancia de metricas.js: el módulo se cargó y ejecutó una sola vez, y ese Map es único.

¿Cuándo es un problema? Cuando el estado compartido debería ser independiente. En las pruebas del Módulo 8, cada test heredaría los recuentos del anterior y fallaría de forma intermitente —de ahí que hayamos exportado reiniciar()—. Y si la aplicación mostrara dos tableros a la vez, las métricas de ambos se mezclarían sin poder separarlas. La alternativa es la misma que aplicamos en crearBacklog(): exportar una fábrica (crearMetricas()) para que cada consumidor tenga su instancia, y reservar el estado de módulo para lo que de verdad es global, como la configuración de la aplicación.

El proyecto ha dejado de ser un fichero para convertirse en una arquitectura. Los tres problemas del principio están resueltos por construcción: cada módulo tiene su propio ámbito, así que dos ficheros pueden declarar PESOS sin enterarse; el orden de carga lo deduce el motor a partir de los import, no el HTML; y las dependencias son explícitas, escritas en las primeras líneas de cada fichero, hasta el punto de que se puede dibujar el grafo y comprobar de un vistazo que todas las flechas apuntan hacia abajo.

Dominas la sintaxis completa. export delante de una declaración o agrupado en una lista al final; import { a, b } con nombres que deben coincidir —no es desestructuración—; as para renombrar en cualquiera de los dos extremos, como hiciste con estaVencida as fechaVencida para resolver un choque real; import * as ns para traer el espacio de nombres completo; export default para el caso de «este fichero es una sola cosa», con sus pros y sus contras frente a las nombradas; y la reexportación en barriles, cómoda pero con un coste de carga que conviene conocer. Sabes que un módulo se ejecuta una sola vez y funciona como un singleton, que las importaciones son enlaces vivos de solo lectura, y que por eso crearBacklog() es una función y no un array exportado.

En el lado del entorno tienes el cuadro completo: <script type="module"> con su ámbito propio, su modo estricto permanente, su defer implícito —que te vendrá muy bien en el Módulo 6— y su exigencia de servidor local por CORS; import() dinámico y await a nivel de módulo como sintaxis que retomarás en 05-06 y 09-05; CommonJS con require/module.exports para reconocerlo cuando aparezca, con su tabla de diferencias frente a ESM —resolución estática frente a dinámica, enlaces vivos frente a copias, navegador sí o no—; y el "type": "module" del package.json que permite ejecutar el proyecto con node js/app.js. Y sabes diagnosticar una dependencia circular: no como un problema de importación que se arregla con un truco, sino como el síntoma de una capa que está mirando hacia arriba.

Nómada Tareas vive ahora en modelo/tarea.js, modelo/tablero.js, modelo/errores.js, datos/backlog.js, util/fechas.js, util/formato.js y js/app.js, y sigue dando los mismos números de siempre: 48 h totales, 45 abiertas, 1 vencida, esfuerzo 124, Iván con 25 h, Lucía con 14 y Marta con 6. Con una diferencia importante: ese datos/backlog.js es hoy un array escrito a mano, y todo el mundo sabe que en la aplicación real los datos vendrán de algún sitio —un fichero, un servidor— y tardarán en llegar. Un lenguaje de un solo hilo no puede quedarse esperando de brazos cruzados mientras eso ocurre, porque mientras espera la interfaz entera se congela. Cómo se programa una espera sin bloquear nada es el otro gran salto del curso, y empieza en JavaScript Asíncrono: Callbacks.