SSG y prerender

Hay contenido que no cambia entre una petición y la siguiente: una landing, un artículo publicado, una página de precios. Renderizarlo en cada visita es pagar cómputo por un resultado idéntico. El Static Site Generation invierte el momento: renderiza esas rutas una sola vez, en el build, y congela el HTML para servirlo tal cual desde un CDN. SolidStart no reinventa esto: delega en Nitro, su servidor subyacente, que sabe recorrer tus rutas y prerenderizarlas. Y lo verdaderamente valioso no es el todo-estático, sino la mezcla: rutas estáticas y dinámicas conviviendo en una misma app.

Prerender en build con Nitro

Le indicas a Nitro qué rutas congelar en app.config.ts. En el build, además de empaquetar el cliente, arranca la app, visita cada ruta listada y escribe su HTML resuelto en disco.

// app.config.ts
import { defineConfig } from "@solidjs/start/config";

export default defineConfig({
  server: {
    prerender: {
      routes: ["/", "/precios", "/blog"],
      crawlLinks: true, // sigue los enlaces para descubrir mas rutas
    },
  },
});

Cada ruta prerenderizada produce dos artefactos: el HTML terminado y el JSON de los datos que sus recursos resolvieron. Ese emparejamiento es el que hace que la hidratación no vuelva a pedir nada: el cliente hidrata el HTML estático y lee los datos del JSON que vino con él. crawlLinks: true ahorra mantener la lista a mano: Nitro parte de las rutas semilla, lee los enlaces del HTML generado y encola los que encuentra, cerrando así el sitio por conexidad.

El descubrimiento por rastreo tiene un límite que conviene conocer: solo encuentra lo que está enlazado. Una ruta a la que no llega ningún enlace desde las semillas —una página huérfana, accesible solo por URL directa— pasará inadvertida y no se congelará. Para esos casos la lista explícita sigue siendo la red de seguridad: semillas más rastreo para lo que forma parte del grafo de enlaces, enumeración para lo que vive fuera de él.

Conviene también vigilar el resultado del rastreo en el otro sentido: si crawlLinks descubre rutas que no querías congelar —una zona de administración enlazada por descuido, una vista con datos ya obsoletos— acabarán como estáticos rancios en producción. Revisar la lista de rutas prerenderizadas que el build reporta es una comprobación barata que evita sorpresas, y una buena costumbre antes de cada despliegue.

El resultado es servible sin servidor de aplicación. Cada visita se resuelve leyendo un fichero del CDN: TTFB mínimo, coste por petición nulo, y una superficie de ataque reducida a servir estáticos. Para contenido que no cambia, es difícil batir esta economía.

Hay un detalle que suele sorprender: durante el prerender, tus server functions se ejecutan de verdad, pero en el entorno del build, no en respuesta a una petición. Si un query lee de una base de datos, esa lectura ocurre mientras compilas, y su resultado queda horneado en el JSON que acompaña al HTML. Por eso el prerender exige que los datos estén disponibles en build —la base poblada, las APIs accesibles desde el proceso de compilación— y por eso una ruta cuyos datos solo existen en producción no puede congelarse tal cual sin repensar de dónde salen.

Rutas dinámicas y datos en build

Una ruta con parámetro —/blog/[slug]— no es una sola página sino una familia. Nitro no puede adivinar los slug; o los descubre por crawlLinks siguiendo enlaces desde un índice, o se los enumeras explícitamente para que congele cada variante.

export default defineConfig({
  server: {
    prerender: {
      // Enumera las variantes conocidas de la ruta dinamica.
      routes: ["/blog/introduccion", "/blog/reactividad", "/blog/streaming"],
      crawlLinks: true,
    },
  },
});

Aquí aflora la trampa capital del prerender, y conviene grabarla. Los datos de una página estática se resuelven en el build, no en la visita. Una server function que lea la cookie de sesión, el usuario actual o la hora exacta no tiene sentido en una ruta prerenderizada: en el build no hay petición, no hay cookie, no hay usuario. Lo que congelas es el resultado de ejecutar esa ruta sin contexto de petición. Por eso solo es candidato a SSG el contenido que es igual para todos y estable en el tiempo.

Esa restricción tiene una lectura positiva: te obliga a separar con claridad los datos públicos y estables de los personales y volátiles. Cuando una página mezcla ambos —un artículo estático con un saludo personalizado en la cabecera—, la solución no es renunciar al prerender, sino congelar la parte pública y traer la personal aparte, hidratándola en el cliente o pidiéndola tras la carga. El prerender no prohíbe la personalización; la empuja a su capa correcta, y esa disciplina suele producir arquitecturas más limpias que las que mezclan todo en un render por petición.

Este es, dicho sea de paso, el mismo principio que gobierna el nivel entero: cada trozo de tu página tiene un momento y un lugar naturales donde renderizarse, y el diseño consiste en llevar cada trozo al suyo, en vez de forzar toda la página a un único modo por comodidad. El prerender es simplemente el extremo del «momento» —lo más temprano posible— para el contenido que puede permitírselo.

flowchart LR
A[build] --> B[Nitro recorre las rutas prerender]
B --> C[HTML estatico mas JSON de datos por ruta]
C --> D[CDN sirve sin computo]
E[ruta dinamica no listada] --> F[servidor la renderiza por peticion]
style C fill:#a6e3a1,color:#11111b
style F fill:#89b4fa,color:#11111b

Una consecuencia práctica: las rutas dinámicas que no enumeras ni se descubren por enlace no dejan de existir —simplemente no se congelan—. Según tu configuración, Nitro las sirve por SSR bajo demanda o devuelve un fallback. Y esto es justo lo que abre la puerta al patrón más útil de todos: prerenderizar el subconjunto conocido y valioso —los cien artículos ya publicados— y dejar que el resto se resuelva dinámicamente. La app no es «estática» ni «dinámica»; es ambas a la vez, decidida ruta por ruta.

Componer estático y dinámico con route rules

La verdadera potencia no es prerenderizar todo, sino mezclar modos en una sola app. Nitro lo permite con las route rules: un mapa de patrones de ruta a políticas de entrega. Una misma base de código sirve así landings congeladas, fichas que se regeneran solas y paneles renderizados por petición.

export default defineConfig({
  server: {
    routeRules: {
      "/": { prerender: true },              // landing: estatica en build
      "/blog/**": { prerender: true },       // articulos: estaticos
      "/producto/**": { swr: 3600 },         // cacheado, revalida en segundo plano
      "/reporte/**": { isr: true },          // se genera al primer acceso y persiste
      "/app/**": { ssr: true },              // panel dinamico por peticion
    },
  },
});

Las políticas cubren el espectro entre lo totalmente estático y lo totalmente dinámico. prerender: true congela en build. swr: 3600 —stale-while-revalidate— sirve la versión cacheada al instante y dispara una regeneración en segundo plano cuando pasa el intervalo, de modo que nadie espera por la actualización. isr —incremental static regeneration, en plataformas que lo soportan— pospone el render al primer acceso y luego persiste el resultado como estático. Y ssr: true deja la ruta plenamente dinámica, resuelta por petición. Eliges por ruta según cuán fresco deba ser el dato y cuánto cómputo estés dispuesto a pagar.

El orden en que listé las políticas no es casual: van de más estático a más dinámico, y esa es la dirección en la que conviene pensarlas. Empieza preguntando si la ruta puede ser prerender; si no, si tolera swr; si tampoco, si le basta isr; y solo al final, si de verdad exige ssr por petición. Bajar por esa escalera peldaño a peldaño te deja siempre en el más barato que la ruta permite, en lugar de saltar al dinámico por costumbre.

El coste del build y cómo mitigarlo

El prerender no es gratis en el otro extremo del tiempo: lo que ahorras por visita lo pagas en el build. Un sitio con decenas de miles de rutas estáticas puede tardar mucho en compilar, porque cada una se renderiza una vez durante la construcción. Ese coste es aceptable para cientos o unos pocos miles de páginas, pero escala mal cuando el catálogo crece sin techo y cada despliegue arrastra una compilación cada vez más larga.

Ahí es donde isr cambia las reglas. En lugar de congelar todas las rutas en el build, pospone el render de cada una a su primer acceso y luego persiste el resultado como estático para las visitas siguientes. Así el build permanece rápido —no renderiza lo que nadie ha pedido aún— y el catálogo puede ser arbitrariamente grande sin inflar el tiempo de compilación. Es prerender perezoso: la primera visita paga un SSR, todas las demás cobran un estático.

Ese matiz —quién paga la primera visita— es la única diferencia real entre prerender e isr, y decide entre ellos. Si la ruta es crítica y no toleras que el primer visitante espere un render, congélala en el build y que nadie pague. Si el catálogo es enorme y la mayoría de sus rutas se visitan rara vez, deja que isr las genere bajo demanda: pagarás un SSR ocasional por página poco vista a cambio de un build que no se dispara. Es el canje clásico entre coste amortizado por adelantado y coste diferido al primer uso.

La lección de fondo es que estático y dinámico no son una frontera sino un continuo, y swr e isr son sus estaciones intermedias. Cuanto más adelantas el render hacia el build, más barata es la visita y más caro y rígido el build; cuanto más lo retrasas hacia la petición, más flexible y fresco el resultado y más cómputo pagas por visita. Elegir dónde parar en ese continuo es toda la decisión, y se toma ruta por ruta.

Una advertencia sobre swr e isr que suele pillar desprevenido: sirven contenido deliberadamente rancio durante la ventana de revalidación. Para un catálogo o un blog eso es inofensivo; para un precio, un saldo o un stock, servir un valor viejo aunque sea unos minutos puede ser inaceptable. La frescura tolerada es un requisito de negocio, no un detalle técnico, y es quien fija el intervalo de revalidación —o quien descarta la revalidación en favor de un SSR por petición—.