SPA y multipágina: el arte de not_found_handling

Servir un archivo que existe es trivial; lo interesante empieza cuando llega una petición a una ruta que no corresponde a ningún archivo. Ese hueco —qué contestar ante /productos/42 cuando en disco no hay ningún productos/42.html— es donde se decide la naturaleza del sitio. Una aplicación de página única quiere que esa ruta cargue su index.html y deje que el enrutador de JavaScript resuelva; un sitio multipágina quiere una página de error honesta con estado 404. El campo not_found_handling codifica esa decisión en una sola línea, y elegir mal produce sitios que devuelven 200 a todo o que se rompen al recargar una ruta interna.

El problema del asset ausente

Cuando el edge recibe una petición, primero busca un asset que coincida con la ruta. Si lo encuentra, lo sirve y ahí acaba todo. La pregunta difícil es qué hacer cuando no lo encuentra, y la respuesta correcta depende por completo de cómo está construido tu sitio.

not_found_handling acepta tres valores, y cada uno describe una filosofía distinta de arquitectura web. El valor por defecto es none: si no hay archivo, se devuelve una respuesta 404 vacía. Sirve para APIs de assets crudos, pero rara vez es lo que quiere un sitio real.

{
  "assets": {
    "directory": "./dist",
    "not_found_handling": "single-page-application"
  }
}

Las dos opciones que importan —single-page-application y 404-page— resuelven el hueco de formas casi opuestas, y entender la diferencia es entender la diferencia entre las dos grandes familias de front-end: la que enruta en el cliente y la que enruta en el servidor.

flowchart TD
R[Peticion a una ruta sin archivo] --> C{Valor de not_found_handling}
C -->|single-page-application| SPA[Sirve index.html con estado 200]
C -->|404-page| P[Sirve el 404.html mas cercano con estado 404]
C -->|none| N[Respuesta 404 vacia]
style SPA fill:#89b4fa,color:#11111b
style P fill:#f9e2af,color:#11111b

La estrategia SPA: todo cae en el índice

Una aplicación de página única carga una sola vez su index.html, y a partir de ahí el enrutador de JavaScript —el de React, el de Vue, el que sea— pinta cada vista sin volver a pedir HTML al servidor. El problema aparece cuando el usuario recarga estando en /productos/42 o comparte ese enlace: el navegador pide esa URL al edge, que no tiene ningún productos/42.html en disco.

Sin ayuda, eso sería un 404, y la aplicación parecería rota justo al entrar por una ruta profunda. El valor single-page-application lo resuelve reenviando cualquier ruta sin archivo al index.html, pero con estado 200. El navegador recibe el shell de la aplicación, el JavaScript arranca, lee la URL actual y el enrutador del cliente pinta la vista de /productos/42 como si nunca se hubiera ido.

El servidor, por tanto, no sabe nada de tus rutas: solo sabe entregar siempre el mismo punto de entrada y ceder el control a tu código. Toda la autoridad sobre qué significa una URL se traslada al cliente, incluida la de declarar que una ruta no existe:

// El enrutador del cliente decide qué es una ruta desconocida
const vista = rutas[window.location.pathname];
render(vista ?? PaginaNoEncontrada);

La estrategia multipágina: un 404 honesto

Un sitio multipágina —un blog, una documentación, un catálogo generado estáticamente— tiene un archivo HTML real por cada página. Aquí una ruta sin archivo casi siempre significa lo que parece: la página no existe. La respuesta correcta no es reenviar al índice, sino servir una página de error con el estado 404, para que navegadores, buscadores y clientes de API entiendan que esa URL no lleva a ningún sitio.

El valor 404-page hace justo eso: ante una ruta sin archivo, busca el 404.html más cercano subiendo por el árbol de directorios y lo sirve con estado 404. Puedes tener un 404.html en la raíz como respaldo global y otros más específicos dentro de subcarpetas —docs/404.html para la documentación—, y el edge elegirá el más próximo a la ruta pedida.

Es la simetría exacta de la estrategia SPA: allí toda ruta desconocida era válida y la autoridad vivía en el cliente; aquí toda ruta desconocida es un error declarado como tal, y la autoridad vive en el servidor que sirve los archivos.

Cómo elegir sin equivocarte

La elección no es de gusto: se deriva de dónde vive el enrutado de tu sitio. Si tus rutas las resuelve JavaScript en el navegador, necesitas SPA; si cada URL corresponde a un archivo generado, necesitas 404-page. Confundirlas produce los dos sitios rotos más comunes de la web.