server: proxy, host y las opciones de desarrollo

El servidor de desarrollo de Vite es una pieza distinta del build: no empaqueta, sirve módulos bajo demanda y recarga en caliente. La clave server gobierna ese servidor, y su opción estrella —proxy— resuelve el problema que todo frontend encuentra el primer día: cómo hablar con una API en otro puerto sin chocar contra CORS. Junto a ella, host y port deciden quién puede alcanzar tu dev server, y un grupo de opciones de seguridad —cors, allowedHosts— existe porque un servidor de desarrollo abierto a la red es una superficie de ataque real. Esta lección cubre el server que de verdad se configura.

proxy: el navegador cree que todo es el mismo origen

El navegador aplica la política del mismo origen: una página servida en un puerto no puede llamar por defecto a una API en otro sin que esta devuelva las cabeceras CORS correctas. En desarrollo eso es una fricción constante, porque tu front vive en un puerto de Vite y tu backend en otro. El proxy la elimina: le dices a Vite que ciertas rutas se reenvíen a otro servidor, y como la petición del navegador va siempre al origen de Vite, no hay cruce de orígenes que bloquear.

import { defineConfig } from "vite"

export default defineConfig({
  server: {
    proxy: {
      // string corto: /api se reenvia a http://localhost:8080/api
      "/api": "http://localhost:8080",
      // objeto: control total
      "/v2": {
        target: "https://backend.internal",
        changeOrigin: true,
        secure: false,
        rewrite: (path) => path.replace(/^\/v2/, ""),
      },
      // websockets
      "/socket": {
        target: "ws://localhost:5174",
        ws: true,
      },
      // clave como expresion regular
      "^/legacy/.*": {
        target: "http://localhost:9000",
        changeOrigin: true,
      },
    },
  },
})

Las tres opciones que marcan la diferencia son changeOrigin, secure y rewrite. changeOrigin reescribe la cabecera Host para que el backend crea que la petición vino de él mismo —imprescindible con hosts virtuales o APIs en la nube—. secure en false acepta certificados HTTPS autofirmados, típico de backends de desarrollo. Y rewrite transforma la ruta antes de reenviarla, para quitar un prefijo que solo existe en tu lado y no en el del servidor real.

flowchart LR
A[navegador] --> B[vite dev server 5173]
B --> C[la ruta casa con una regla de proxy]
C --> D[reenvia al backend 8080]
D --> E[respuesta vuelve por vite]
E --> A
style C fill:#89b4fa,color:#11111b

host, port y el acceso desde la red

Por defecto el dev server solo escucha en localhost, alcanzable únicamente desde tu máquina. Poner host en true lo hace escuchar en todas las interfaces, y entonces un móvil o un compañero en la misma red pueden abrirlo por tu IP local: la forma canónica de probar en un dispositivo real. port fija el puerto y strictPort decide qué pasa si está ocupado: por defecto Vite salta al siguiente libre, pero en un pipeline donde otra herramienta espera un puerto exacto conviene que falle en vez de moverse.

server: {
  host: true,        // escucha en todas las interfaces, accesible desde la LAN
  port: 5173,
  strictPort: true,  // falla si el puerto esta ocupado en vez de saltar
  open: "/panel",    // abre el navegador directamente en esa ruta
  warmup: {
    clientFiles: ["./src/main.ts", "./src/App.vue"],
  },
}

open arranca el navegador por ti, y si le das una ruta abre directamente en ella. warmup es una optimización más fina y moderna: le adelantas a Vite qué archivos vas a pedir primero para que los transforme antes de que los solicites, recortando el tiempo hasta la primera pantalla en proyectos grandes. Es gratis y casi nadie lo usa.

Un detalle que ahorra depuraciones: cuando sirves la app bajo un subdirectorio, la clave base y el server.origin deben concordar con esa ruta pública, o los assets se pedirán a una URL que no existe. Es el mismo mapa de rutas que impone el proxy, visto ahora desde el lado de los recursos estáticos en lugar del de las llamadas a la API.

cors, allowedHosts y seguridad en dev

Un dev server no es un juguete inofensivo: sirve tu código fuente y, mal expuesto, deja que un sitio malicioso o un host suplantado lea cosas que no debería. Por eso las versiones recientes de Vite endurecieron los defaults, y conviene entender las dos palancas. cors controla qué orígenes externos pueden pedir recursos a tu dev server; dejarlo abierto de par en par ya no es el default. allowedHosts es la defensa contra el DNS rebinding: la lista de nombres de host con los que se puede llegar a tu servidor, para que un dominio atacante que resuelva a tu IP no pueda hablar con él.

server: {
  cors: false,
  allowedHosts: ["app.local", ".mi-tunel.dev"],
  hmr: {
    overlay: true,
  },
}

https, hmr y watch: afinar el bucle

Cerrado el proxy y el acceso, quedan tres opciones que afinan el bucle de desarrollo minuto a minuto: el cifrado, la reconexión en caliente y el vigilante de archivos. Ninguna es glamurosa, y las tres deciden si trabajar en el proyecto se siente instantáneo o pastoso.

A veces necesitas HTTPS en desarrollo: para probar APIs que exigen origen seguro, service workers, o cookies con atributos estrictos que el navegador solo respeta sobre TLS. La opción https acepta las rutas del certificado y la clave, y en la práctica se combina con un plugin que genera certificados de confianza local para no pelearte con los avisos del navegador.

server: {
  https: { key: "./certs/key.pem", cert: "./certs/cert.pem" },
  hmr: { host: "localhost", protocol: "ws", overlay: true },
  watch: {
    ignored: ["**/coverage/**", "**/.git/**"],
  },
}

El reemplazo de módulos en caliente casi nunca hay que tocarlo, pero cuando el dev server vive tras un proxy o en un puerto distinto del que ve el usuario, hmr deja fijar el host, el puerto o el protocolo del websocket para que el cliente sepa a dónde reconectarse. El overlay decide si los errores se pintan sobre la página o solo van a la consola.

watch ajusta el vigilante de archivos. ignored excluye carpetas que no aportan —artefactos de cobertura, salidas de otras herramientas— y que, vigiladas, solo gastan recursos y disparan recargas espurias. En proyectos grandes o sobre sistemas de archivos de red, afinar el watcher es la diferencia entre un dev server ágil y uno que consume un núcleo entero sin motivo.