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.resolvedice 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
Resuelto
Elige una respuesta en cada pregunta.
¿Qué es un especificador desnudo (bare specifier)?
¿Para qué sirve un import map?
¿Qué hace
with { type: "json" }en un import?¿Qué devuelve
import.meta.resolve("fecha")?
Ordena la salida: Resolver con un import map
Resuelto
Una página con un import map. Ordena las URLs que imprimiría la consola.
1<!-- https://ejemplo.com/app/index.html -->2<script type="importmap">3 {4 "imports": {5 "fecha": "/libs/fecha@2.1/index.js",6 "utils/": "/src/utils/"7 }8 }9</script>10 11<script type="module">12 console.log(import.meta.resolve("fecha"));13 console.log(import.meta.resolve("utils/texto.js"));14 console.log(import.meta.resolve("./local.js"));15</script>Consola, de arriba abajo
- https://ejemplo.com/src/utils/texto.js
- https://ejemplo.com/app/local.js
- https://ejemplo.com/libs/fecha@2.1/index.js
"fecha" está en el mapa tal cual. "utils/" termina en barra: es un prefijo, y todo lo que empiece así se resuelve dentro de /src/utils/. ./local.js es una ruta relativa: el mapa no la toca y se resuelve desde la página.
Detective: Un nombre que el navegador no conoce
Resuelto
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.
Paso 2: ¿cómo lo arreglas?