CSS en el build: code splitting, extracción y orden

En desarrollo, Vite inyecta el CSS a través de JavaScript para lograr un HMR instantáneo. En el build eso provocaría un destello de contenido sin estilo y un render bloqueado a la espera del JS, así que Vite extrae el CSS a archivos .css reales, los parte por chunk asíncrono y los enlaza con etiquetas <link>. Pero partir el CSS reabre una herida antigua del lenguaje: la cascada depende del orden de inserción, y el orden entre archivos partidos no siempre es el que darías por supuesto. Esta lección va de esa tensión y de cómo desactivarla.

De la inyección por JS a la extracción a archivos

En desarrollo, un import "./estilos.css" hace que Vite inyecte una etiqueta <style> mediante JavaScript. Es ideal para el HMR —puede intercambiar los estilos sin recargar la página— pero sería malo en producción: el render dependería de que el JS se ejecute, con el consiguiente destello sin estilo, ese FOUC que delata una cascada que llega tarde. Por eso el build hace lo contrario: extrae todo el CSS a archivos .css y emite etiquetas <link rel="stylesheet">, de modo que el navegador pueda pintar con estilo antes de ejecutar una sola línea de JavaScript.

Esta asimetría entre dev y build es deliberada, no un descuido: cada mitad elige el compromiso opuesto. En desarrollo manda la velocidad de iteración, y el CSS por JS permite reemplazarlo en caliente sin recargar. En producción manda la experiencia de carga, y solo un archivo enlazado deja pintar sin esperar al script. El mismo import de CSS produce dos comportamientos distintos según la mitad, y entender esa dualidad evita sorpresas al pasar de una a otra.

flowchart TB
subgraph Dev
  d1[import de css] --> d2[Vite inyecta un style por JS]
  d2 --> d3[HMR intercambia estilos sin recargar]
end
subgraph Build
  b1[import de css] --> b2[extrae a un archivo css con hash]
  b2 --> b3[emite un link por chunk]
  b3 --> b4[render con estilo antes de ejecutar JS]
end
style d2 fill:#89b4fa,color:#11111b
style b2 fill:#a6e3a1,color:#11111b

cssCodeSplit: un CSS por chunk

La opción build.cssCodeSplit está activa por defecto. Con ella, cada chunk asíncrono que importa CSS obtiene su propio archivo .css extraído, que se carga solo cuando ese chunk se carga. Una ruta que el usuario nunca visita jamás descarga su CSS: el estilo se parte y viaja con el código al que pertenece.

import { defineConfig } from "vite";

export default defineConfig({
  build: {
    cssCodeSplit: true, // por defecto: un .css por chunk asincrono
  },
});

Ponerlo en false concatena todo el CSS en un único archivo que se carga por adelantado. El orden se vuelve más simple y determinista, pero pierdes la carga bajo demanda; a veces es lo que quieres al empaquetar una librería de componentes, donde consumidores distintos cargan piezas distintas y prefieres una hoja única con precedencia estable a un puñado de fragmentos cuyo orden no controlas.

Qué chunk se lleva qué CSS

El reparto sigue el grafo. El CSS que importa el entry va a la hoja crítica que se carga de inmediato; el CSS que importa un chunk asíncrono —una ruta perezosa, un componente diferido— viaja en la hoja de ese chunk y no se descarga hasta que el chunk se pide.

dist/assets/
├─ index.4f2a9c.css     # css critico de la ruta inicial
├─ perfil.a7b3e2.css    # solo se descarga al entrar en /perfil
└─ ajustes.c19d4a.css   # solo al entrar en /ajustes

• CSS del entry va a la hoja crítica, con <link> en el head, siempre.
• CSS de un chunk asíncrono viaja en su hoja propia, cargada con el chunk.
• CSS compartido por varios chunks lo coloca Vite para no duplicarlo.

CSS Modules: alcance local

Un archivo .module.css recibe un trato especial: sus nombres de clase se transforman en identificadores locales únicos con hash, y en tu JavaScript importas un mapa de esos nombres. Eso lo distingue del CSS global, que vierte sus reglas sobre todo el documento sin barrera alguna.

/* card.module.css */
.card { padding: 1rem; }
.card:hover { transform: translateY(-2px); }

import styles from "./card.module.css";
// styles.card === "card__card___a1b2c" en el build
element.className = styles.card;

El patrón del nombre generado se gobierna con css.modules.generateScopedName, que ya viste en el nivel de configuración: legible en desarrollo, compacto en producción. La clave es que dos componentes pueden declarar .card sin pisarse, porque físicamente no comparten nombre. Los módulos no cambian el modelo de la cascada —siguen siendo reglas globales—; lo que hacen es garantizar que dos autores no colisionen por accidente, resolviendo el problema del nombrado aunque no el del orden.

Los módulos añaden además composes, que permite que una clase local herede de otra sin duplicar reglas ni depender de la cascada:

/* boton.module.css */
.base { padding: 0.5rem 1rem; border-radius: 6px; }
.primario { composes: base; background: royalblue; }

El orden de carga y la cascada

La cascada de CSS es sensible al orden: entre dos reglas de igual especificidad que apuntan al mismo elemento, gana la última insertada. Con una sola hoja concatenada, “la última insertada” es simplemente el orden del código fuente, estable y legible. En cuanto partes el CSS por chunk y cargas los chunks bajo demanda, “la última insertada” pasa a depender de la navegación y de los tiempos de red: visitar la ruta A y luego la B puede dar un orden, y entrar directo a la B, otro. Es el análogo en CSS de una condición de carrera: las mismas reglas, distintas intercalaciones, distintos píxeles.

Conviene recordar qué decide, en CSS, qué regla gana cuando varias apuntan al mismo elemento, de mayor a menor peso:

• La importancia: una declaración !important vence a las normales.
• Las capas: @layer fija una precedencia explícita entre grupos de reglas.
• La especificidad: un selector más específico gana a uno más general.
• El orden de inserción: a igualdad de todo lo anterior, gana la última.

El code splitting solo puede tocar el último eslabón, el orden. Por eso apoyarse en cualquiera de los tres superiores —y sobre todo en las capas— vuelve el resultado inmune al azar de la carga.

Vite se esfuerza por preservar un orden determinista basado en el grafo de módulos, pero las fronteras asíncronas y los tiempos de import dinámico aún pueden sorprenderte. La mitigación correcta no es pelear por fijar el orden, sino eliminar la dependencia del orden. La herramienta de 2026 para ello son las capas de cascada, @layer: declaras la precedencia de forma explícita y por nombre, de modo que qué regla gana lo decide su capa, no el azar de qué <link> analizó antes el navegador.

@layer base, components, utilities;

@layer components {
  .btn { background: royalblue; }
}

El orden de la primera línea fija la precedencia para siempre: utilities gana a components, y este a base, sin importar en qué archivo ni en qué momento se inserte cada regla. Has movido la decisión de precedencia del cuándo se cargó al en qué capa está declarado, que es exactamente el eje que el code splitting no puede desordenar.