Saltar al contenido
Módulos

Import maps y atributos de importación

Lección 3 de 49 min3 ejercicios

En Node.js escribes import { format } from "date-fns" y funciona, porque Node.js busca en node_modules. En el navegador, ese mismo import falla: el navegador solo entiende rutas y URLs. Los import maps le enseñan qué significa cada nombre, y los atributos de importación le dicen qué tipo de archivo está importando.

Un import map

Un <script type="importmap">, antes de cualquier módulo, asocia nombres con URLs:

<script type="importmap">
  {
    "imports": {
      "date-fns": "https://esm.sh/date-fns@4.1.0",
      "componentes/": "/src/componentes/"
    }
  }
</script>

<script type="module">
  import { format } from "date-fns";
  import { Boton } from "componentes/boton.js";

  console.log(format(new Date(), "dd/MM/yyyy"));
</script>
  • Una clave sin barra final ("date-fns") reemplaza ese nombre exacto.
  • Una clave con barra final ("componentes/") es un prefijo: todo lo que empiece así se resuelve dentro de esa carpeta.

Así, el código de tus módulos se escribe igual que en un proyecto con Node.js, y la versión de cada dependencia se cambia en un solo lugar.

Scopes

Un mapa puede tener reglas distintas según quién importa, con "scopes". Por ejemplo, para que una parte antigua del sitio siga usando otra versión:

{
  "imports": { "fecha": "/libs/fecha@3/index.js" },
  "scopes": {
    "/legado/": { "fecha": "/libs/fecha@2/index.js" }
  }
}

Y para saber a qué URL se resuelve algo, sin cargarlo, está import.meta.resolve("fecha").

Atributos de importación (ES2025)

Un módulo JavaScript se ejecuta al importarlo. ¿Qué pasa si importas un archivo .json y el servidor, por error o a propósito, devuelve código? Por seguridad, para importar algo que no es JavaScript hay que decir qué tipo esperas, con with:

import config from "./config.json" with { type: "json" };
import traducciones from "./es.json" with { type: "json" };

console.log(config.version, traducciones.saludo);

El runtime comprueba que el archivo sea de verdad JSON y lo entrega ya convertido en objeto. Funciona en los navegadores modernos, Node.js, Deno y Bun. También con el import() dinámico:

const { default: datos } = await import("./datos.json", { with: { type: "json" } });

En los navegadores existe además type: "css", que importa una hoja de estilos para usarla en Web Components:

import estilos from "./tarjeta.css" with { type: "css" };
document.adoptedStyleSheets = [...document.adoptedStyleSheets, estilos];

Resumen

  • El navegador solo entiende rutas y URLs; un import map le enseña nombres como "date-fns".
  • Claves exactas y prefijos terminados en /; "scopes" para reglas por carpeta.
  • import.meta.resolve dice a qué URL se resolvería un import.
  • Atributos de importación (ES2025): with { type: "json" } importa JSON de forma segura.
  • with { type: "css" } importa hojas de estilo en los navegadores.

¡A practicar!

Tu progreso se guarda en este navegador.

Autoevaluación: Nombres para los módulos

Elige una respuesta en cada pregunta.

  1. ¿Qué es un especificador desnudo (bare specifier)?

  2. ¿Para qué sirve un import map?

  3. ¿Qué hace with { type: "json" } en un import?

  4. ¿Qué devuelve import.meta.resolve("fecha")?

Ordena la salida: Resolver con un import map

Una página con un import map. Ordena las URLs que imprimiría la consola.

<!-- https://ejemplo.com/app/index.html --><script type="importmap">  {    "imports": {      "fecha": "/libs/fecha@2.1/index.js",      "utils/": "/src/utils/"    }  }</script> <script type="module">  console.log(import.meta.resolve("fecha"));  console.log(import.meta.resolve("utils/texto.js"));  console.log(import.meta.resolve("./local.js"));</script>

Consola, de arriba abajo

  1. https://ejemplo.com/src/utils/texto.js
  2. https://ejemplo.com/app/local.js
  3. https://ejemplo.com/libs/fecha@2.1/index.js

Detective: Un nombre que el navegador no conoce

Un import que funciona en Node.js falla en el navegador. Encuentra la línea y elige el arreglo.

Consola

Uncaught TypeError: Failed to resolve module specifier "date-fns". Relative references must start with either "/", "./", or "../".

Paso 1: toca la línea de código que causa el error.

domina-js · JavaScript en español, gratis y paso a paso.