Guía
Sitios estáticos
Una página HTML por archivo de src/routes/. stil run build deja el sitio listo para subir, y solo las páginas con islas llevan JavaScript.
Una línea en vite.config.ts
import ascua from "vite-plugin-ascua";
export default { plugins: [ascua({ site: true })] };Con eso, cada archivo de src/routes/ es una página, vite la sirve en
desarrollo y vite build escribe en dist/ un HTML por ruta. No hay servidor
que escribir ni entradas de cliente y servidor: queda una carpeta de archivos
para Hull, busybox httpd, tower-http o cualquier CDN.
src/routes/index.ts → dist/index.html
src/routes/acerca.ts → dist/acerca/index.html
src/routes/pedidos/index.ts → dist/pedidos/index.html
src/routes/pedidos/[id].ts → dist/pedidos/7/index.html, una por id
src/routes/docs/[...rest].ts → dist/docs/guia/inicio/index.html, con sus barras
src/routes/api/[[v]].ts → /api y /api/2: el segmento es opcional
src/routes/(marketing)/precios.ts → dist/precios/index.html: el grupo no sale en la URL
src/routes/404.ts → dist/404.html
src/routes/500.ts → dist/500.html: la página de error
src/routes/_layout.ts envuelve todas las páginas
src/routes/pedidos/_layout.ts envuelve las de pedidos/, dentro del de la raíz
src/routes/admin/_middleware.ts corre antes de las de admin/ (con servidor)Un archivo que empieza por _ no es una página. [...rest] va al final y
atrapa lo que quede de la URL: /docs/guia/inicio le da rest = "guia/inicio".
El nombre entre corchetes lo eliges tú: es el del parámetro que llega a la página.
Con corchetes dobles, [[v]], el segmento es opcional: la misma página
atiende /api —con v sin definir— y /api/2. En un sitio estático,
/api sale siempre y paths() dice qué valores de v generar.
Una carpeta entre paréntesis, como (marketing)/, agrupa rutas sin aparecer
en la URL: sirve para darles su propio _layout.ts o _middleware.ts sin
cambiar sus direcciones. Si dos archivos acaban dando la misma URL —dos
grupos con un precios.ts, o [[v]].ts junto a un index.ts—, es un
error, en vez de quedarse con uno en silencio.
Una página
// src/routes/acerca.ts
export const title = "Acerca";
export default function Acerca() {
return view`<section><h1>Acerca</h1></section>`;
}El default es el componente de la página y title va al <title>. El código
de las páginas corre al construir y no llega al navegador: queda como HTML.
Con parámetros
// src/routes/pedidos/[id].ts
export const title = ({ id }: { id: string }) => `Pedido ${id}`;
export function paths() {
return PEDIDOS.map((p) => ({ id: p.id }));
}
export default function Pedido({ id }: { id: string }) {
return view`<article><h1>Pedido ${id}</h1></article>`;
}[id] es un segmento variable, y la página lo recibe como prop. paths()
dice qué páginas generar —una por objeto— y puede ser asíncrona. Es
obligatoria: sin ella, el build no sabría qué ids existen.
Datos: load()
// src/routes/pedidos/[id].ts
import { notFound } from "vite-plugin-ascua/site";
export async function load({ id }: { id: string }) {
const pedido = await leerPedido(id);
if (!pedido) throw notFound();
return pedido;
}
type Props = { id: string; data: Awaited<ReturnType<typeof load>> };
export const title = ({ data }: Props) => `Pedido ${data.numero}`;
export const description = ({ data }: Props) => `${data.lineas.length} líneas`;
export default function Pedido({ data }: Props) {
return view`<article><h1>Pedido ${data.numero}</h1></article>`;
}load() corre al construir —en desarrollo, en cada petición— y lo que
devuelve llega a la página, al título y a la descripción como data. Es el
sitio para leer archivos, una base de datos o una API: nada de eso llega al
navegador. description va a <meta name="description">.
throw notFound() responde con la página 404 en desarrollo y con servidor.
Rutas que no son páginas
Un archivo cuyo nombre, sin el .ts, conserva una extensión es ese archivo:
// src/routes/sitemap.xml.ts → dist/sitemap.xml
export default function Mapa() {
return `<?xml version="1.0"?><urlset>…</urlset>`;
}El default devuelve el contenido, que puede ser asíncrono; con parámetros y
load(), igual que una página. Sirve para un sitemap.xml, un
feed.xml, un índice de búsqueda en .js o un .json.
Lo interactivo: islas
Una página es HTML. Lo que tenga que responder al usuario va en una isla, que la página usa como cualquier componente:
// src/islands/contador.ts
export const IslaContador = defineIsland("contador", { inicial: p.number }, Contador);
// src/routes/index.ts
view`<section><IslaContador inicial=${3}/></section>`;Las islas de src/islands/ se registran solas. Una página que usa alguna recibe
el script que las hidrata y solo los módulos de las islas que usa, con sus
chunks y sus hojas pedidos por delante; una que no usa ninguna sale sin
JavaScript. Por eso conviene una isla por archivo: si dos islas se
definen en el mismo módulo, la página que usa una descarga las dos. Cómo
funcionan las islas está en SSR e islas.
El layout
// src/routes/_layout.ts
import type { Children } from "ascua";
export default function Layout(props: { path: string; children: Children }) {
const marco = view`<div><header>…</header><main></main></div>`;
props.children(marco.querySelector("main")!);
return marco;
}Es un componente con hijos: recibe la ruta (path), sus parámetros (params) y
dónde poner la página (children). Puede
haber uno por carpeta, y se anidan: el de la raíz envuelve al de pedidos/,
que envuelve a sus páginas.
Más cosas en el <head>
export const head = ({ data }: Props) => `
<meta property="og:title" content="${data.titulo}">
<link rel="canonical" href="https://ejemplo.cl/pedidos/${data.id}/">`;head —una cadena o una función de los props— va al <head> tal cual,
sin escapar: es HTML que escribe la ruta, no texto de un usuario.
El esqueleto: shell
Si hay un index.html en la raíz, es el esqueleto de todas las páginas. Pasa
por Vite como siempre, así que sus <link> a hojas globales salen con su hash.
La página va donde esté <!--ascua-->, o al principio de <body>. Sin
index.html, se usa uno mínimo.
Si la raíz del sitio es otra cosa —una portada hecha a mano—, el esqueleto
puede ser otro archivo —la opción shell—, y index.html sigue siendo una página más de Vite. Así
está hecha esta documentación:
ascua({ site: { routes: "rutas", shell: "docs/esqueleto.html" } });A cada página se le añaden su <title>, un <style> con los estilos de los
componentes que aparecen en ella —y solo esos— y, si tiene islas, su script.
Al subirlo
/pedidos/7 es dist/pedidos/7/index.html, que cualquier servidor de archivos
entrega como índice de la carpeta. Para la página de error, en busybox httpd:
E404:/404.htmlen el httpd.conf del sitio.
Con servidor
Si las páginas tienen que renderizarse en cada petición —datos que cambian a cada rato, una página por usuario—, el mismo sitio sale como servidor:
ascua({ site: { mode: "server" } });stil run build
node dist/server/index.mjs # PORT=3000 por defectovite build deja el cliente en dist/client/ y el servidor en
dist/server/index.mjs, con todo dentro: no necesita node_modules para
arrancar. Sirve los archivos del cliente —con caché larga para los que llevan
hash— y renderiza cada página al pedirla. Las rutas variables ya no necesitan
paths(): cualquier valor llega a load(), que decide con
notFound(). Para montarlo dentro de otro servidor, handle recibe la URL
o un Request y devuelve el estado, las cabeceras y el cuerpo
(serve(puerto) es el que arranca el suyo):
import { handle } from "./dist/server/index.mjs";
const { status, headers, body } = await handle("/pedidos/7");Con servidor, las rutas reciben formularios y cada página sale con la seguridad puesta: CSP, cabeceras y cookies seguras.
Middleware
Un _middleware.ts corre antes de las rutas de su carpeta y de las de
dentro: antes de las acciones y de load(). Sirve para lo que se repetiría
en cada una, como exigir una sesión:
// src/routes/admin/_middleware.ts
import { redirect, type MiddlewareContext } from "vite-plugin-ascua/site";
export default async function ({ cookies, locals }: MiddlewareContext) {
const id = await cookies.getSigned("session");
if (!id) throw redirect("/login");
locals.user = await findUser(id);
}// src/routes/admin/orders.ts
export async function load(_: object, { locals }: LoadContext) {
return listOrders(locals.user!.id);
}Recibe { url, request, params, cookies, locals, setHeaders, next }:
Cortar.
throw redirect(…)manda a otra página ythrow notFound()da la 404; ni la acción niload()llegan a correr. Si el formulario venía deenhance(), la redirección le llega igual.locals. Lo que deje ahí lo recibenload(), las acciones y los layouts (en la proplocals). Para tiparlo, se amplíaLocals:tsdeclare module "vite-plugin-ascua/site" { interface Locals { user?: { id: string; name: string }; } }setHeaders. Añade cabeceras a la respuesta, sea la página, una redirección o un error. Mandan sobre las del kit.Envolver con
next(). Corre lo de dentro —los middlewares interiores, la acción,load(), la página— y devuelve suResponse, que se puede cambiar o reemplazar. Un error de dentro llega como excepción:ts// src/routes/_middleware.ts export default async function ({ next }: MiddlewareContext) { const start = performance.now(); try { const response = await next(); response.headers.set("server-timing", `page;dur=${performance.now() - start}`); return response; } catch (error) { reportError(error); return new Response("Something went wrong", { status: 500 }); } }Devolver una
Responsesin llamar anext()corta ahí. Un middleware que no llama anext()ni devuelve nada deja seguir, como siempre.
Si hay uno en la raíz y otro en admin/, corren los dos, primero el de la
raíz; con next(), el de la raíz envuelve al de admin/. Una URL que no
existe recibe la 404 de la raíz y solo los middlewares de la raíz; una ruta
de admin/ que lanza notFound() pasa por los de admin/. Como necesita una petición, un
sitio estático con middleware no se construye.
Rutas de API: GET, PUT, DELETE…
Una ruta puede exportar una función por método HTTP, como en Fresh. Cada una
recibe los parámetros, la petición, las cookies y locals, y devuelve un
Response:
// src/routes/api/posts/[id].ts
import { notFound, type RequestHandler } from "vite-plugin-ascua/site";
export const GET: RequestHandler<{ id: string }> = async ({ params }) => {
const post = await db.posts.find(params.id);
if (!post) throw notFound();
return Response.json(post);
};
export const PUT: RequestHandler<{ id: string }> = async ({ params, request }) =>
Response.json(await db.posts.update(params.id, await request.json()));
export const DELETE: RequestHandler<{ id: string }> = async ({ params }) => {
await db.posts.delete(params.id);
return new Response(null, { status: 204 });
};- Se exportan
GET,POST,PUT,PATCH,DELETEyOPTIONS.HEADusaGET. Un método que la ruta no atiende es un 405, conallowdiciendo cuáles sí. - Conviven con la página y las acciones. Si existe la función del método,
responde ella; si no, lo de siempre: la página para
GET, las acciones paraPOST. - Los que escriben, solo desde el mismo origen. Como los formularios: una
petición con
Originde otro sitio recibe un 403. SinOrigin—otro servidor,curl— pasa;security.originsañade orígenes de confianza. - Pasan por los middlewares, pueden lanzar
redirect()onotFound(), y necesitan servidor: un sitio estático con ellas no se construye.
La página de error: 500.ts
Un error que nadie captura —en load(), en una acción, al pintar— responde un
500. Con src/routes/500.ts, ese 500 es una página del sitio, con su layout,
y recibe lo que se lanzó en error:
// src/routes/500.ts
import { view } from "ascua";
import type { ErrorPageProps } from "vite-plugin-ascua/site";
export const title = "Algo falló";
export default function Error500(props: ErrorPageProps) {
console.log(props.error); // ya se escribió en el log del servidor
return view`<h1>Algo falló</h1><p>Lo estamos mirando.</p>`;
}El error se escribe en la consola del servidor, y la página decide qué enseñar:
en producción, mejor poco. Una ruta de API, una ruta de archivo o
enhance() esperan otra cosa que HTML, así que ahí el 500 sigue siendo el de
siempre. Si la propia 500.ts falla, también. En un sitio estático sale como
dist/500.html, para que la sirva quien sirve el sitio.
Navegar sin recargar: partials
Con partials, un enlace interno no recarga la página: se pide la página
nueva y se reemplazan solo las regiones marcadas con data-partial. Lo de
fuera —la cabecera, una isla que reproduce audio, un buscador a medio
escribir— se queda como estaba.
// vite.config.ts
export default { plugins: [ascua({ site: { partials: true } })] };// src/routes/_layout.ts
export default function Layout(props: LayoutProps) {
const page = view`
<div>
<header><Search/></header>
<main data-partial="main"></main>
</div>`;
props.children(page.querySelector("main")!);
return page;
}- Qué cambia. Las regiones, el
<title>, la descripción y el idioma; las hojas y módulos que traiga la página nueva se añaden. Las islas de la región que sale se liberan y las de la que entra se hidratan. - Sin región marcada, se reemplaza el
<body>entero: igual sin recargar. - Historial. Atrás y adelante funcionan, con su scroll. Un enlace con ancla baja hasta ella.
- Lo que no intercepta. Enlaces a otro origen, con
target,downloadorel="external", con una tecla pulsada, y los que estén dentro dedata-partials="false". - Si algo no encaja —la página nueva no tiene las mismas regiones, no es HTML, falla la red—, navega de la forma de siempre.
Pide la página entera, la misma que vería el navegador, así que funciona
igual en un sitio estático. A cambio, todas las páginas llevan un script
pequeño, también las que no tienen islas. Al terminar, document recibe el
evento ascua:navigate.
La petición lleva la cabecera x-ascua-partial: 1, por si un middleware
quiere distinguirla. El servidor responde la página entera igual: recortarla
ahorraría poco más de 1 kB comprimido por navegación, y la misma URL con dos
respuestas distintas obliga a cuidar cada caché por el camino.
Con Deno, de principio a fin
No hace falta Node: Deno instala los paquetes de npm, corre Vite y sirve el sitio construido.
deno run -A npm:create-ascua my-site --template server
cd my-site
deno install
deno task dev # o: deno task build
deno run -A dist/server/index.mjsComo stil, Deno no instala versiones publicadas hace menos de un día; en ese
caso, deno install --minimum-dependency-age 0.
En Bun, Deno y Workers
dist/server/index.mjs arranca igual en Node, Bun y Deno:
node dist/server/index.mjs
bun dist/server/index.mjs
deno run -A dist/server/index.mjsAl lado queda dist/server/worker.mjs, el mismo sitio sin nada de Node:
un fetch(request, env) que recibe un Request y devuelve un Response,
que es la forma de Cloudflare Workers y de
workerd, el runtime de Workers que
se puede alojar en servidores propios. Los archivos de dist/client/ los pide
a env.ASSETS, y ASCUA_SECRET lo lee de env:
// wrangler.jsonc
{
"name": "my-site",
"main": "dist/server/worker.mjs",
"compatibility_date": "2026-09-01",
"assets": { "directory": "dist/client", "binding": "ASSETS" }
}En un workerd propio, ASSETS es un servicio de disco:
using Workerd = import "/workerd/workerd.capnp";
const config :Workerd.Config = (
services = [
(name = "main", worker = .site),
(name = "assets", disk = (path = "/srv/my-site/dist/client", writable = false)),
],
sockets = [ (name = "http", address = "*:8080", http = (), service = "main") ],
);
const site :Workerd.Worker = (
modules = [ (name = "worker.mjs", esModule = embed "dist/server/worker.mjs") ],
compatibilityDate = "2026-09-01",
bindings = [
(name = "ASSETS", service = "assets"),
(name = "ASCUA_SECRET", fromEnvironment = "ASCUA_SECRET"),
],
);No hace falta nodejs_compat. Los tests del kit corren el mismo sitio, con
formularios, cookies firmadas y el límite del cuerpo, en Node, Bun, Deno y
workerd.
Opciones
| Por defecto | ||
|---|---|---|
routes |
src/routes |
Dónde están las páginas |
islands |
src/islands |
Lo que se hidrata; sin islas no hay script |
shell |
index.html |
La base de cada página |
mode |
static |
O server |
lang |
es |
El idioma de lo que ve quien usa el sitio: los mensajes de field y las respuestas del kit (403, 404, 405, 413). Los errores de build siguen a LANG; los avisos del runtime en la consola salen en inglés |
security |
activada | Con servidor: CSP, cabeceras, cookies y origen. Ver Seguridad |
Y lo que puede exportar una ruta:
default |
La página: un componente de los props. En una ruta-archivo, el contenido |
title |
El <title>: una cadena o una función de los props |
description |
<meta name="description">, igual |
head |
HTML para el <head>, igual |
lang |
El lang del <html> de esa página, sobre el del esqueleto: un sitio en dos idiomas comparte esqueleto |
paths() |
Qué páginas generar en una ruta variable |
load() |
Los datos: llegan como data. Recibe los parámetros y { url, request, cookies, locals } |
actions |
Con servidor, lo que recibe sus formularios. Ver Formularios |