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

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

ts
// 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

ts
// 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()

ts
// 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:

ts
// 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:

ts
// 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

ts
// 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>

ts
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:

ts
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.html

en 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:

ts
ascua({ site: { mode: "server" } });
sh
stil run build
node dist/server/index.mjs       # PORT=3000 por defecto

vite 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):

ts
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:

ts
// 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);
}
ts
// 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 y throw notFound() da la 404; ni la acción ni load() llegan a correr. Si el formulario venía de enhance(), la redirección le llega igual.

  • locals. Lo que deje ahí lo reciben load(), las acciones y los layouts (en la prop locals). Para tiparlo, se amplía Locals:

    ts
    declare 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 su Response, 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 Response sin llamar a next() corta ahí. Un middleware que no llama a next() 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:

ts
// 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, DELETE y OPTIONS. HEAD usa GET. Un método que la ruta no atiende es un 405, con allow diciendo 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 para POST.
  • Los que escriben, solo desde el mismo origen. Como los formularios: una petición con Origin de otro sitio recibe un 403. Sin Origin —otro servidor, curl— pasa; security.origins añade orígenes de confianza.
  • Pasan por los middlewares, pueden lanzar redirect() o notFound(), 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:

ts
// 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.

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.

ts
// vite.config.ts
export default { plugins: [ascua({ site: { partials: true } })] };
ts
// 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, download o rel="external", con una tecla pulsada, y los que estén dentro de data-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.

sh
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.mjs

Como 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:

sh
node dist/server/index.mjs
bun dist/server/index.mjs
deno run -A dist/server/index.mjs

Al 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:

jsonc
// 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:

capnp
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