resolve: alias, extensiones, conditions y dedupe

Cada import de tu código es una pregunta —qué archivo es este especificador— y la clave resolve es donde le dictas la respuesta a Vite. Sus ejes reescriben una parte concreta del algoritmo de resolución de Node: alias cambia el especificador antes de buscarlo, extensions decide qué probar cuando falta la extensión, conditions y mainFields eligen entre variantes de un paquete, y dedupe fuerza una copia única. En Vite 8 todo esto corre sobre el oxc-resolver escrito en Rust. Dominar estos cinco ejes es controlar la última costura entre tu import y el byte que ejecuta el navegador.

alias: reescribir el especificador

alias intercepta un especificador y lo sustituye por otro antes de resolverlo. Su uso más común es matar los imports relativos profundos: en vez de subir cuatro carpetas con puntos, defines un @ que apunta a src y escribes rutas absolutas desde la raíz del proyecto. La forma de objeto hace coincidencia por prefijo; conviene resolver la ruta a un absoluto real con las utilidades de URL de Node para que funcione igual en cualquier plataforma.

import { defineConfig } from "vite"
import { fileURLToPath, URL } from "node:url"

export default defineConfig({
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
      "@ui": fileURLToPath(new URL("./src/components", import.meta.url)),
    },
  },
})

Cuando necesitas más que un prefijo —capturar un patrón, reordenar el resultado, o desviar un paquete entero hacia otro— usas la forma de array, donde cada entrada tiene un find y un replacement, y find puede ser una expresión regular con grupos.

resolve: {
  alias: [
    { find: /^~(.+)/, replacement: "$1" },      // ~lib pasa a lib
    { find: "lodash", replacement: "lodash-es" }, // fuerza la variante ESM
  ],
}

extensions, mainFields y conditions

extensions es la lista de sufijos que Vite prueba cuando el import los omite. El orden importa y tiene coste real: cada extensión es un intento de disco, y un import sin extensión que acaba en la sexta entrada pagó cinco accesos fallidos. Menos entradas resuelven más rápido, y escribir siempre la extensión en tus propios imports elimina el problema de raíz.

resolve: {
  extensions: [".mjs", ".js", ".mts", ".ts", ".jsx", ".tsx", ".json"],
  mainFields: ["browser", "module", "jsnext:main", "main"],
  conditions: ["module", "browser", "development|production"],
}

mainFields y conditions deciden, ante un paquete con varias variantes, cuál servir. mainFields es el mecanismo veterano: prueba campos del package.json en orden —module para el ESM que quiere el bundler, browser para sustituir builds enteros— antes de caer en main. conditions es el mecanismo moderno: selecciona ramas dentro del campo exports. Fíjate en el token development|production: Vite lo resuelve a development cuando sirves y a production cuando construyes, de modo que una librería puede exponer una build con avisos en dev y una limpia en prod con una sola entrada.

Vite parte de un conjunto de conditions por defecto sensato —incluye module, browser y la pareja development con production— y lo que tú declaras en resolve.conditions se antepone a esa base en lugar de reemplazarla. Por eso rara vez necesitas listar las estándar: basta con añadir la tuya, como una condition internal que sirva el fuente de un paquete del monorepo sin compilarlo, y dejar que las demás sigan en su sitio.

Ese detalle —anteponer, no reemplazar— es fácil de pasar por alto y explica un fallo típico: alguien redefine resolve.conditions con una sola entrada creyendo que añade, y en realidad tira por la borda browser y module, con lo que medio ecosistema deja de resolver su variante correcta y aparecen errores que no tienen nada que ver con el import que se tocó.

dedupe y symlinks: una sola copia

dedupe resuelve un problema de correctitud, no de estética. Si dos partes de tu grafo acaban resolviendo dos copias físicas de React, tienes dos registros de hooks distintos y un componente que cruza la frontera revienta con el célebre Invalid hook call. Listar el paquete en dedupe obliga a Vite a colapsar todas las referencias a una única instalación, y el problema desaparece de raíz.

resolve: {
  dedupe: ["react", "react-dom"],
  preserveSymlinks: false,
}

El factor silencioso que acompaña a dedupe son los enlaces simbólicos. En un monorepo con pnpm o con workspace:, los paquetes locales son symlinks, y el resolutor debe decidir si identifica un módulo por su ruta real o por la del enlace. Con preserveSymlinks en false —lo habitual— sigue el enlace hasta el archivo real, que es justo lo que permite que dedupe reconozca dos referencias como la misma copia. Ponerlo en true puede reintroducir la duplicación que creías resuelta.

Conviene además saber que dedupe opera sobre nombres de paquete, no sobre rangos: colapsa a una sola copia física las referencias a react, pero no puede inventar una versión común si dos partes del grafo exigen mayores incompatibles. Cuando eso ocurre, el problema deja de ser de resolución y pasa a ser de versiones, y se arregla una capa más arriba, en los rangos declarados, con las mismas armas del nivel de los catalogs.

flowchart LR
A[import en tu codigo] --> B[resolve.alias reescribe]
B --> C[prueba resolve.extensions]
C --> D[lee package.json]
D --> E[elige por conditions y mainFields]
E --> F[dedupe fuerza copia unica]
F --> G[ruta final del modulo]
style F fill:#a6e3a1,color:#11111b

Los paths del tsconfig y el bundler

Hay un alias que Vite no ve por defecto: los paths del tsconfig.json. Los define TypeScript para su type-checker, pero el resolutor de Vite no los lee, así que un @/ que compila sin quejas en el editor puede fallar en el build si no lo replicas. Tienes tres salidas: duplicarlo a mano en resolve.alias, instalar un plugin que lea el tsconfig, o —lo preferible— migrar esos alias internos a los imports del package.json, que no necesitan ningún espejo.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

El caso más engañoso es el que compila y arranca en desarrollo pero rompe en el build de producción, porque el pre-bundle de dependencias y el empaquetado final no siempre comparten cada matiz de resolución. Si un import solo falla al construir, sospecha de un alias o un path que existe para el type-checker pero que el bundler nunca vio.

Cada mecanismo que eliminas es una fuente menos de desincronización entre el type-checker, el bundler y el runtime. De ahí la regla que cierra el eje de la resolución: minimiza los alias propietarios. Cuanto más delegues en exports, imports y las conditions estándar, menos configuración frágil tendrás que mantener sincronizada a mano, y más portable será tu proyecto entre herramientas. La config de resolución más robusta es, casi siempre, la más pequeña.