vite-patterns

Patrones de Vite

Patrones para la herramienta de compilación y servidor de desarrollo para proyectos Vite 8+. Cubre configuración, variables de entorno, configuración de proxy, modo librería, pre-empaquetado de dependencias y problemas comunes de producción.

Cuándo usar

• Configurando vite.config.ts o vite.config.js
• Configurando variables de entorno o archivos .env
• Configurando el proxy del servidor de desarrollo para backends de API
• Optimizando la salida de compilación (chunks, minificación, assets)
• Publicando librerías con build.lib
• Solucionando problemas de pre-empaquetado de dependencias o interoperabilidad CJS/ESM
• Depurando HMR, el servidor de desarrollo o errores de compilación
• Eligiendo u ordenando plugins de Vite

Cómo funciona

• Modo de desarrollo sirve archivos fuente como ESM nativo — sin empaquetado. Las transformaciones ocurren bajo demanda por solicitud de módulo, por eso los arranques en frío son rápidos y el HMR es preciso.
• Modo de compilación usa Rolldown (v7+) o Rollup (v5–v6) para empaquetar la aplicación para producción con tree-shaking, división de código y minificación basada en Oxc.
• Pre-empaquetado de dependencias convierte dependencias CJS/UMD a ESM una vez mediante esbuild y almacena en caché el resultado bajo node_modules/.vite, para que los arranques posteriores omitan el trabajo.
• Plugins comparten una interfaz unificada entre desarrollo y compilación: el mismo objeto de plugin funciona tanto para las transformaciones bajo demanda del servidor de desarrollo como para la canalización de producción.
• Variables de entorno se insertan estáticamente en tiempo de compilación. Las variables con prefijo VITE_ se convierten en constantes públicas en el bundle; todo lo que no tenga ese prefijo es invisible para el código cliente.

Ejemplos

Estructura de configuración

Configuración básica

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: { '@': new URL('./src', import.meta.url).pathname },
  },
})

Configuración condicional

// vite.config.ts
import { defineConfig, loadEnv } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig(({ command, mode }) => {
  const env = loadEnv(mode, process.cwd())   // solo prefijo VITE_ (seguro)

  return {
    plugins: [react()],
    server: command === 'serve' ? { port: 3000 } : undefined,
    define: {
      __API_URL__: JSON.stringify(env.VITE_API_URL),
    },
  }
})

Opciones clave de configuración

Clave	Valor por defecto	Descripción
root	'.'	Raíz del proyecto (donde está index.html)
base	'/'	Ruta base pública para assets desplegados
envPrefix	'VITE_'	Prefijo para variables de entorno expuestas al cliente
build.outDir	'dist'	Directorio de salida
build.minify	'oxc'	Minificador ('oxc', 'terser' o false)
build.sourcemap	false	true, 'inline' o 'hidden'

Plugins

Plugins esenciales

La mayoría de las necesidades de plugins están cubiertas por un puñado de paquetes bien mantenidos. Recurre a estos antes de escribir los tuyos propios.

Plugin	Propósito	Cuándo usarlo
@vitejs/plugin-react-swc	HMR de React + Fast Refresh mediante SWC	Predeterminado para aplicaciones React (más rápido que la variante Babel)
@vitejs/plugin-react	HMR de React + Fast Refresh mediante Babel	Solo si necesitas plugins de Babel (emotion, decoradores MobX)
@vitejs/plugin-vue	Soporte para SFC de Vue 3	Aplicaciones Vue
vite-plugin-checker	Ejecuta tsc + ESLint en un hilo de trabajo con superposición de HMR	Cualquier aplicación TypeScript — Vite NO verifica tipos durante vite build
vite-tsconfig-paths	Honra los alias paths de tsconfig.json	Siempre que ya tengas alias en tsconfig.json
vite-plugin-dts	Emite archivos .d.ts en modo librería	Al publicar librerías TypeScript
vite-plugin-svgr	Importa SVG como componentes de React	Aplicaciones React que usan SVG como componentes
rollup-plugin-visualizer	Informe de treemap/sunburst del bundle	Auditorías periódicas del tamaño del bundle (usar enforce: 'post')
vite-plugin-pwa	PWA con configuración cero + Workbox	Aplicaciones con capacidad offline

Aviso crítico: vite build transpila pero NO verifica tipos. Los errores de tipo llegan silenciosamente a producción a menos que añadas vite-plugin-checker o ejecutes tsc --noEmit en CI.

Creación de plugins personalizados

La creación es poco común: la mayoría de las necesidades están cubiertas por plugins existentes. Cuando necesites uno, comienza en línea en vite.config.ts y solo extrae si se reutiliza.

// vite.config.ts — plugin en línea mínimo
function myPlugin(): Plugin {
  return {
    name: 'my-plugin',                       // obligatorio, debe ser único
    enforce: 'pre',                           // 'pre' | 'post' (opcional)
    apply: 'build',                           // 'build' | 'serve' (opcional)
    transform(code, id) {
      if (!id.endsWith('.custom')) return
      return { code: transformCustom(code), map: null }
    },
  }
}

Hooks clave: transform (modificar fuente), resolveId + load (módulos virtuales), transformIndexHtml (inyectar en HTML), configureServer (añadir middleware de desarrollo), hotUpdate (HMR personalizado — reemplaza el obsoleto handleHotUpdate en v7+).

Módulos virtuales usan la convención de prefijo \0 — resolveId devuelve '\0virtual:my-id' para que otros plugins lo omitan. El código de usuario importa 'virtual:my-id'.

Para la API completa de plugins, consulta vite.dev/guide/api-plugin. Usa vite-plugin-inspect durante el desarrollo para depurar la canalización de transformación.

API de HMR

Los plugins de framework (@vitejs/plugin-react, @vitejs/plugin-vue, etc.) manejan el HMR automáticamente. Recurre a import.meta.hot directamente solo cuando construyas almacenes de estado personalizados, herramientas de desarrollo o utilidades independientes del framework que necesiten persistir estado entre actualizaciones.

// src/store.ts — HMR manual para un módulo vanilla
if (import.meta.hot) {
  // Persistir estado entre actualizaciones (debe MUTAR, nunca reasignar .data)
  import.meta.hot.data.count = import.meta.hot.data.count ?? 0

  // Limpiar efectos secundarios antes de que el módulo sea reemplazado
  import.meta.hot.dispose((data) => clearInterval(data.intervalId))

  // Aceptar las actualizaciones de este módulo
  import.meta.hot.accept()
}

Todo el código de import.meta.hot se elimina mediante tree-shaking en las compilaciones de producción — no se necesita eliminar la guarda.

Variables de entorno

Vite carga .env, .env.local, .env.[mode] y .env.[mode].local en ese orden (las posteriores sobrescriben las anteriores); los archivos *.local están en .gitignore y están destinados a secretos locales.

Acceso del lado del cliente

Solo las variables con prefijo VITE_ se exponen al código del cliente:

import.meta.env.VITE_API_URL   // cadena
import.meta.env.MODE            // 'development' | 'production' | personalizado
import.meta.env.BASE_URL        // valor de configuración base
import.meta.env.DEV             // booleano
import.meta.env.PROD            // booleano
import.meta.env.SSR             // booleano

Uso de variables de entorno en la configuración

// vite.config.ts
import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd())          // solo prefijo VITE_ (seguro)
  return {
    define: {
      __API_URL__: JSON.stringify(env.VITE_API_URL),
    },
  }
})

Seguridad

VITE_ NO es un límite de seguridad

Cualquier variable con prefijo VITE_ se inserta estáticamente en el bundle del cliente en tiempo de compilación. La minificación, la codificación base64 y la desactivación de mapas fuente NO la ocultan. Un atacante decidido puede extraer cualquier variable VITE_ del JavaScript enviado.

Regla: Solo valores públicos (URLs de API, flags de funcionalidad, claves públicas) van en variables VITE_. Los secretos (tokens de API, URLs de bases de datos, claves privadas) DEBEN vivir en el servidor detrás de una API o función serverless.

La trampa de loadEnv('')

// MALO: pasar '' como tercer argumento carga TODAS las variables de entorno — incluidos secretos del servidor —
// y las hace disponibles para insertar en el código del cliente mediante `define`.
const env = loadEnv(mode, process.cwd(), '')

// BUENO: lista de prefijos explícita
const env = loadEnv(mode, process.cwd(), ['VITE_', 'APP_'])

Mapas fuente en producción

Los mapas fuente en producción filtran tu código fuente original. Desactívalos a menos que los subas a un rastreador de errores (Sentry, Bugsnag) y los elimines localmente después:

build: {
  sourcemap: false,                                  // valor por defecto — mantenlo así
}

Lista de verificación de .gitignore

• .env.local, .env.*.local — sobrescrituras de secretos locales
• dist/ — salida de compilación
• node_modules/.vite — caché de pre-empaquetado (entradas obsoletas causan errores fantasma)

Proxy del servidor

// vite.config.ts — server.proxy
server: {
  proxy: {
    '/foo': 'http://localhost:4567',                    // abreviatura de cadena

    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true,                               // necesario para backends con host virtual
      rewrite: (path) => path.replace(/^\/api/, ''),
    },
  },
}

Para proxy de WebSocket, añade ws: true a la configuración de la ruta.

Optimización de compilación

Chunks manuales

// vite.config.ts — build.rolldownOptions
build: {
  rolldownOptions: {
    output: {
      // Forma de objeto: agrupar paquetes específicos
      manualChunks: {
        'react-vendor': ['react', 'react-dom'],
        'ui-vendor': ['@radix-ui/react-dialog', '@radix-ui/react-popover'],
      },
    },
  },
}

// Forma de función: dividir por heurística
manualChunks(id) {
  if (id.includes('node_modules/react')) return 'react-vendor'
  if (id.includes('node_modules')) return 'vendor'
}

Rendimiento

Evita archivos barrel

Los archivos barrel (index.ts que reexportan todo de un directorio) fuerzan a Vite a cargar cada archivo reexportado incluso cuando importas un solo símbolo. Esta es la causa número 1 de ralentización del servidor de desarrollo señalada por la documentación oficial.

// MALO — importar una utilidad fuerza a Vite a cargar todo el barrel
import { slash } from '@/utils'

// BUENO — importación directa, solo se carga el archivo
import { slash } from '@/utils/slash'

Sé explícito con las extensiones de importación

Cada extensión implícita fuerza hasta 6 verificaciones del sistema de archivos mediante resolve.extensions. En bases de código grandes, esto se acumula.

// MALO
import Component from './Component'

// BUENO
import Component from './Component.tsx'

Reduce tsconfig.json allowImportingTsExtensions + resolve.extensions solo a las extensiones que realmente uses.

Calienta rutas de acceso frecuente

server.warmup.clientFiles pre-transformar entradas conocidas antes de que el navegador las solicite — eliminando la cascada de solicitudes de carga en frío en aplicaciones grandes.

// vite.config.ts
server: {
  warmup: {
    clientFiles: ['./src/main.tsx', './src/routes/**/*.tsx'],
  },
}

Perfilado de servidores de desarrollo lentos

Cuando vite dev se siente lento, comienza con vite --profile, interactúa con la aplicación, luego presiona p+enter para guardar un .cpuprofile. Cárgalo en Speedscope para encontrar qué plugins están consumiendo tiempo — generalmente los hooks buildStart, config o configResolved en plugins de la comunidad.

Modo librería

Al publicar un paquete npm, usa build.lib. Dos detalles importantes importan más que la configuración:

1. Los tipos no se emiten — añade vite-plugin-dts o ejecuta tsc --emitDeclarationOnly por separado.
2. Las dependencias pares DEBEN externalizarse — las pares no listadas se empaquetan en tu librería, causando errores de tiempo de ejecución duplicados en los consumidores.

// vite.config.ts
build: {
  lib: {
    entry: 'src/index.ts',
    formats: ['es', 'cjs'],
    fileName: (format) => `my-lib.${format}.js`,
  },
  rolldownOptions: {
    external: ['react', 'react-dom', 'react/jsx-runtime'],  // cada dependencia par
  },
}

Externalizaciones SSR

Las configuraciones simples de createServer({ middlewareMode: true }) son territorio de autores de frameworks. La mayoría de las aplicaciones deberían usar Nuxt, Remix, SvelteKit, Astro o TanStack Start en su lugar. Lo que ajustarás como usuario de framework es la configuración de externalización cuando las dependencias se rompen en SSR:

// vite.config.ts — opciones ssr
ssr: {
  external: ['node-native-package'],           // mantener como require() en el bundle SSR
  noExternal: ['esm-only-package'],            // forzar empaquetado en la salida SSR (corrige la mayoría de errores SSR)
  target: 'node',                              // 'node' o 'webworker'
}

Pre-empaquetado de dependencias

Vite pre-empaqueta dependencias para convertir CJS/UMD a ESM y reducir el número de solicitudes.

// vite.config.ts — optimizeDeps
optimizeDeps: {
  include: [
    'lodash-es',                              // forzar pre-empaquetado de dependencias pesadas conocidas
    'cjs-package',                            // dependencias CJS que causan problemas de interoperabilidad
    'deep-lib/components/**',                 // glob para importaciones profundas
  ],
  exclude: ['local-esm-package'],             // debe ser ESM válido si se excluye
  force: true,                                // ignorar caché, re-optimizar (depuración temporal)
}

Problemas comunes

El desarrollo no coincide con la compilación

El modo desarrollo usa esbuild/Rolldown para transformaciones; la compilación usa Rolldown para empaquetar. Las librerías CJS pueden comportarse de manera diferente entre ambos. Siempre verifica con vite build && vite preview antes de desplegar.

Chunks obsoletos después del despliegue

Las nuevas compilaciones producen nuevos hashes de chunks. Los usuarios con sesiones activas solicitan nombres de archivo antiguos que ya no existen. Vite no tiene una solución integrada. Mitigaciones:

• Mantén los archivos antiguos de dist/assets/ activos durante una ventana de despliegue
• Captura errores de importación dinámica en tu enrutador y fuerza una recarga de página

Docker y contenedores

Vite se vincula a localhost por defecto, lo que es inalcanzable desde fuera de un contenedor:

// vite.config.ts — configuración Docker/contenedor
server: {
  host: true,                                  // vincular 0.0.0.0
  hmr: { clientPort: 3000 },                   // si está detrás de un proxy inverso
}

Acceso a archivos en monorepos

Vite restringe el servicio de archivos a la raíz del proyecto. Los paquetes fuera de la raíz están bloqueados:

// vite.config.ts — acceso a archivos en monorepo
server: {
  fs: {
    allow: ['..'],                             // permitir directorio padre (raíz del espacio de trabajo)
  },
}

Anti-patrones

// MALO: establecer envPrefix a '' expone TODAS las variables de entorno (incluidos secretos) al cliente
envPrefix: ''

// MALO: asumir que require() funciona en …

[truncado para traducción]