Módulos en el navegador vs en Node

ESM te da una sintaxis única, pero se ejecuta en dos mundos que resuelven y cargan módulos de formas opuestas. El navegador los trae por HTTP con especificadores completos e import maps; Node los busca en el disco con extensiones, el campo type y el algoritmo del campo exports. Escribes lo mismo; el runtime hace cosas muy distintas.

El navegador: script type=module

Marcar un script como módulo cambia su semántica por completo respecto a un script clásico:

<script type="module">
  import { app } from "./app.js";
  app();
</script>

Un módulo se difiere por defecto (se ejecuta tras parsear el HTML, en orden), corre en modo estricto, tiene su propio ámbito (nada de globales accidentales), se descarga con CORS y se evalúa una sola vez aunque se incluya varias veces. La restricción clave: el navegador solo entiende URLs. Un especificador desnudo como import x from "lodash" no es una URL válida y falla, salvo que un import map lo traduzca.

Frente a un script clásico, el módulo cambia varias reglas de golpe:

Dos atributos afinan la carga: async en un módulo lo desacopla del orden y lo ejecuta en cuanto llega (útil para analítica independiente), y nomodule marca un script de respaldo que solo ejecutan los navegadores sin soporte de módulos —hoy casi extintos, pero la técnica sigue siendo el patrón de degradación—.

Cuando el navegador carga un módulo, lo parsea, descubre sus import y va a buscar cada dependencia por la red antes de evaluar, repitiendo el proceso en cascada por todo el grafo. Sin bundler, un árbol profundo se traduce en muchas peticiones encadenadas: es exactamente la latencia que el pre-bundle de Vite y el bundling de producción eliminan al aplanar el grafo en pocos archivos.

Import maps: especificadores desnudos en la web

Un import map le enseña al navegador a resolver nombres desnudos hacia URLs reales, sin build step:

<script type="importmap">
{
  "imports": {
    "lodash": "https://esm.sh/lodash-es@4",
    "@/": "/src/"
  }
}
</script>

Con eso, import _ from "lodash" y import util from "@/util.js" funcionan directamente en el navegador. En 2026 los import maps son baseline en todos los navegadores modernos, e incluso se admiten múltiples import maps que se fusionan, lo que facilita composiciones e inyección de dependencias sin empaquetar.

Combinados con CDNs de ESM como esm.sh o jsDelivr —que sirven cualquier paquete de npm ya convertido a ESM—, los import maps permiten prototipar una app con dependencias reales sin instalar nada ni levantar un bundler. Para producción, una etiqueta link rel=modulepreload sobre las dependencias del mapa elimina la cascada de descubrimiento, precargando los módulos en paralelo al HTML.

Los import maps también admiten scopes: reglas de resolución que solo aplican bajo cierta ruta, de modo que dos partes de la app usen versiones distintas de la misma dependencia. Es una capacidad que el bundling tradicional no ofrece con tanta naturalidad, y anticipa un futuro de micro-frontends compuestos en el propio navegador.

Node: el campo type y las extensiones

Node decide si un archivo es ESM o CommonJS con dos señales. La extensión manda de forma absoluta cuando es explícita; si no, decide el campo type del package.json más cercano:

flowchart TD
J[archivo .js] -->|type module| C[ESM]
J -->|type commonjs o ausente| K[CommonJS]
M[archivo .mjs] --> C
N[archivo .cjs] --> K
style C fill:#a6e3a1,color:#11111b
style K fill:#fab387,color:#11111b

Es decir: .mjs es siempre ESM, .cjs es siempre CommonJS, y un .js depende de si el package.json declara "type": "module". Sin ese campo, el .js se interpreta como CommonJS por compatibilidad histórica. La recomendación en 2026 para proyectos nuevos:

{
  "name": "mi-app",
  "type": "module"
}

En ESM no hay __dirname; para resolver rutas relativas a un archivo se usa import.meta.url, que ambos runtimes exponen. Es el puente portable entre los dos mundos:

const datos = new URL("./datos.json", import.meta.url);
const config = import.meta.resolve("./config.js");

La ambigüedad histórica del .js —que podía ser ESM o CJS según el contexto— fue una fuente inagotable de confusión. La guía en 2026 es inequívoca: declara "type": "module" en todo proyecto nuevo, usa .js para tu código ESM y reserva .cjs para los pocos scripts heredados que aún dependan de require. Explícito y sin sorpresas.

Resolución: dos algoritmos distintos

Aquí está la diferencia de fondo. El navegador hace resolución de URL: un especificador relativo se resuelve contra la URL del módulo actual, las extensiones son obligatorias (./util no existe, ./util.js sí) y no hay índices de directorio. Node hace resolución de disco: recorre node_modules hacia arriba, aplica el campo exports e imports, prueba extensiones y respeta las conditions (node, browser, import, require, default).

Las conditions son el punto donde ambos mundos se tocan: un mismo paquete puede exponer una implementación bajo la condition browser (que usa APIs del DOM) y otra bajo node (que usa node:fs). El bundler, al empaquetar para web, activa browser y elige la variante correcta; por eso una librería isomórfica funciona igual en servidor y cliente sin que tú cambies el import.

Node también admite subpath imports internos: un mapa imports en package.json con claves que empiezan por almohadilla (como #utils) crea alias privados del paquete, invisibles desde fuera. Es la versión de Node de los alias que en el navegador da el import map y en el bundler da resolve.alias. Tres mecanismos, un mismo objetivo: desacoplar el nombre lógico de la ruta física.

Un detalle que unifica el ecosistema en 2026: los módulos internos de Node se importan con el prefijo explícito node:, como en import { readFile } from "node:fs/promises". Ese prefijo deja claro que es un builtin y no un paquete de node_modules, y permite a los bundlers y a runtimes como Deno o Bun tratarlos sin ambigüedad.

Un bundler existe, en buena parte, para reconciliar ambos: aplica el algoritmo de Node en tiempo de build (resuelve node_modules, respeta exports, elige la condition browser) y produce archivos con URLs y extensiones que el navegador sí carga. Escribes import _ from "lodash" una vez y funciona en los dos mundos gracias a esa traducción.