@janit/fu
v0.6.3
Published
A minimal islands framework on Preact 11 and rolldown. Builds a Worker for celld; runs on Deno, Node and Bun.
Maintainers
Readme
Fresh Urquell
A minimal islands framework: file-system routing, SSR and hydration on Preact 11, built by rolldown into one Worker module. Runs on celld (and anything else that runs Workers), and on Deno, Node and Bun through a runner on srvx.
No Vite, no Babel, no esbuild. The bundler, JSX transform and CSS engine are all Rust.
core router + render + client + navigation + hmr runtime + app, errors, types
drivers build + dev + cli + shared driver glue + rolldown plugins
server asset store and static files, the runner for Node/Deno/Bun, the in-process test handlerWhat this is
Fresh Urquell is inspired by Deno Fresh, and aims to be just a single pint of glue code — enough to form a functional, simple framework on top of known good libraries, and no more. The interesting work already lives in Preact, rolldown, srvx and lightningcss; this only binds them together.
It is experimental and primarily just for myself. Use it accordingly.
Installing it
On Node (22.12 or later) or Bun:
npm i @janit/fu preact @preact/signals
npx fu dev # and: npx fu buildOn Deno 2, the packages have to land in a real node_modules/, and the JSX
settings are yours to give:
deno add npm:@janit/fu npm:preact@^11 npm:@preact/signals
deno run -A npm:@janit/fu/cli dev .// deno.json
{
"nodeModulesDir": "auto",
"compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "preact" }
}@preact/signals is an optional peer: leave it out if no island imports it. A
build fails on an import that resolves to nothing, rather than producing a
server that cannot start.
npm is the only channel. The framework hands its own runtime modules to
rolldown, so it must be a real directory on disk, which an npm install is. It
was published to JSR up to 0.0.4 and is no longer updated there, so do not
install it from JSR: Deno keeps JSR packages as remote https: modules, and a
bundler cannot fetch one.
The npm package ships compiled JavaScript, because Deno refuses to type-strip
TypeScript inside node_modules.
Quick start
npm install # once: installs the toolchain (rolldown, lightningcss, srvx)
deno task dev # example app, dev server with HMR on localhost:1337
deno task build # example app, production build
deno task test # unit tests, no browser
deno task check # format, lint, types (framework and the example apps), testsThe CLI behind those tasks is fu dev [root] [--port N] [--host H],
fu build [root] [--out DIR] and fu serve [root] [--port N] [--host H] [--out DIR],
which serves a build on the runtime running it. The root defaults to the working directory and must contain
routes/. The dev server listens on --port (1337) and its HMR socket on the
port after it. It binds to 127.0.0.1 and answers only to loopback names
(localhost, 127.0.0.1, any *.localhost), because it hands out source and
stack traces. --host 0.0.0.0 opens it to the network, for a container or
another device, and HMR works from any of the machine's own addresses (a LAN
or Tailscale IP); --host <name> binds and admits that one name. The page's
HMR client dials the host the page came from, and works on plain http by IP,
where the browser has no crypto.randomUUID. fu --help and
fu --version do what they say. fu dev stops on SIGINT (Ctrl+C) and on
SIGTERM: it closes the HMR socket, the dev server and the watchers, and exits
with code 0, within two seconds at the latest.
A build is one artifact for every runtime:
.output/
server/index.mjs the Worker: `export default { fetch }`, and what worker.ts exports
server/serve.mjs the runner: serves that Worker on Node, Deno or Bun
public/_fu/ the client files, under content-hashed namesRun it on whichever runtime you like:
node example/.output/server/serve.mjs
bun example/.output/server/serve.mjs
deno run -A example/.output/server/serve.mjsThe runner listens on PORT (3000 if unset or empty; anything but a port
number is an error naming it) and HOST (every interface if unset or empty),
hands the Worker the process environment as env and .output/public as
env.ASSETS, and stops on SIGINT and SIGTERM, giving waitUntil work still
running two seconds to finish. It uses each runtime's own server: Deno.serve,
Bun.serve, node:http. On Deno without -A it needs
--allow-net --allow-env --allow-read (read access covering .output/). For
celld, see Deploying to celld.
The build resolves packages as a Worker does (the workerd, worker, import
and default export conditions, then module and main); fu dev runs in
the dev server's own process and resolves as that runtime does (node, then
import). A package that ships a different build for Node can therefore
behave differently under fu dev than in the build: serve the build, or run
it under celld, before trusting a new dependency.
A build minifies the client, serves it from /_fu/ under content-hashed names
with a year-long immutable cache, and
announces as modulepreload what the page is going to run, so that its
islands start loading in one round trip after the HTML: the chunks the boot
module imports statically (on every page), and, for each island the page
rendered, that island's chunk and the chunks it imports statically. A page
without islands announces none of the island code, and a chunk reached only
by a dynamic import() (a library an island loads on demand, the navigation
runtime) is never announced: it is fetched when it is asked for. The dev
server serves plain names from / and preloads nothing. It links /style.css
only while the app has a stylesheet (CSS imported by a route, the shell or an
island): an app without CSS requests no such file. The link is decided on every
render, so it appears on the first page rendered after the first stylesheet is
written; a page already open gets it through the hot reload message that
announces the sheet, and no reload is needed. A build is unaffected.
Knowing when the page is hydrated
Islands hydrate after the page has loaded, because the boot module imports
their chunks dynamically. When the first hydration pass is over the boot
module sets data-fu-hydrated (empty) on <html> and dispatches a plain
fu:hydrated event on window; the names are HYDRATED_ATTR and
HYDRATED_EVENT in @janit/fu/client. The pass is over when every island on
the page has been hydrated or has failed: a chunk that does not load or an
island that throws is logged, as before, and does not hold the signal back or
stop the others. A page with no islands is signalled too. It fires once per
document; a client navigation does not fire it again, fu:nav already means
that the islands that arrived are hydrated. The server never renders the
attribute. The signal is independent of the navigation runtime, which loads
beside the islands: it can be installed before or after the signal. A test
that drives a browser waits for html[data-fu-hydrated]; code that must run
after hydration listens for the event, after checking the attribute (a
listener added late would miss it).
Deploying to celld
The Worker is what celld runs. The app owns its wrangler.jsonc; fu never
writes one, and fu build prints the lines it needs:
{
"name": "my-app",
"main": ".output/server/index.mjs",
"compatibility_date": "2026-10-01",
"assets": {
"directory": ".output/public",
"binding": "ASSETS",
"run_worker_first": ["/_fu/*"]
}
}binding must be ASSETS: that is where the Worker looks for the asset
store. run_worker_first sends the client files through the Worker, which
serves them from that store with the year-long cache header and answers
anything else under /_fu/ with an uncacheable 404; without it celld serves
them itself, with its default max-age=0. An app that serves its own static
files through assets() lists their paths there too, or sets
true to run every request through the Worker. Put those files in the asset
directory as part of your own build step: fu writes only public/_fu/, and
clears only that when --out names a directory of yours. The Worker is one
file, so "no_bundle": true works, or celld's esbuild may bundle it again.
Nothing of the app runs when the Worker is loaded. On the first request
prepare(env) from worker.ts runs, if there is one, and only then are
app.ts, the shell and the routes evaluated, so code at module scope can
read what prepare set up. That holds for what the app reaches through
app.ts and the routes; a module that worker.ts itself imports runs when
the Worker is loaded, as any import does.
worker.ts
Optional, at the project root, beside app.ts:
import type { Env } from "@janit/fu";
import { bindEnv } from "./lib/env.ts";
/** Called once per isolate, before the app's modules run. */
export async function prepare(env: Env): Promise<void> {
bindEnv(env);
}
/** Everything else is exported by the Worker as it is: handlers and classes. */
export const scheduled = {
async scheduled(_event: unknown, _env: Env, _ctx: unknown): Promise<void> {},
};
export class Room { /* a Durable Object */ }prepare is called, not exported; a prepare that throws fails that request
and is tried again on the next. (A route module that throws at module scope
fails every request until the next deploy, as a failed import would.) Under
fu dev each rebuild is a fresh Worker, so prepare runs again after every
save, and whatever it opened stays open: dev only, but a prepare that opens
connections will collect them across a long session. Every other export is re-exported by the
Worker unchanged, which is how a Durable Object class, a scheduled or a
queue handler reaches celld; celld refuses a deploy whose exports are not
all handlers or classes. A default export, export *, a destructured export
and a prepare that is not a function fail the build. fu adds no wrapper for
Durable Objects, KV, queues or cron: they are celld's, reached through env.
ctx.env, ctx.waitUntil, ctx.assets
app.use(async (ctx) => {
const res = await ctx.next();
ctx.waitUntil(report(ctx.env.LOG_URL as string, ctx.url.pathname));
return res;
});ctx.envis the Worker'senv: on celld thevarsand bindings ofwrangler.jsonc; under the runner andfu devthe process environment. On celldvarsreachenvand notprocess.env, so read configuration from here, or copy what a library wants intoprocess.envinprepare(env). Type your own by augmenting theEnvinterface:declare module "@janit/fu" { interface Env { LOG_URL: string } }.ctx.waitUntil(promise)keeps the isolate alive until the promise settles: celld may stop an isolate once the response is sent, and work not handed over here can be cut off. Under the runner a rejection is logged, and stopping the server waits for what is still running (two seconds at most); underfu devthe work runs on and a rejection is logged.ctx.assetsis the asset store,env.ASSETS: celld's binding, or.output/publicunder the runner (the client directory infu dev).nullwhere there is none. See Static files.
Project shape
app.ts (or app.tsx) middleware chain (optional)
state.ts your State type (a convention, not scanned)
middleware/*.ts one concern per file (a convention; app.ts imports them)
routes/_app.tsx shell wrapping every page (optional)
routes/_error.tsx error page (optional)
routes/index.tsx -> /
routes/about.tsx -> /about
routes/blog/[slug].tsx -> /blog/:slug
routes/files/[...rest].tsx -> /files/:rest*
islands/Counter.tsx interactive, hydrated on the client
islands/counter.module.css CSS Modules, scopedEvery .ts, .tsx, .js and .jsx file under routes/ is a route, except:
files and directories starting with _ (framework files, and a place for your
own helpers, such as routes/_parts/), tests (*_test.*, *.test.*) and
.d.ts files. The same goes for islands/.
A file name is taken literally, so routes/a+b.tsx answers /a+b. A param
name ([slug], [...rest]) must be an identifier; [my-id] is refused at
startup, and so are two files that would answer the same path
(blog.tsx and blog/index.tsx).
A route exports a page component, and optionally handlers:
export const handlers = {
GET: () => ({ renderedAt: new Date().toISOString() }),
};
export default function About(ctx: PageContext) {
return <p>{(ctx.data as { renderedAt: string }).renderedAt}</p>;
}Return a Response from a handler to short-circuit; return anything else and
it lands on ctx.data. A route with no page has nothing to render that data
with, so there a handler must return a Response; forgetting to is a 500.
Handlers are keyed by HTTP method. A page renders for GET and HEAD whether
or not it has a GET handler, so a route with only POST still shows its form.
HEAD runs the GET handler and drops the body. OPTIONS is answered for you,
and any other method without a handler is a 405 carrying Allow.
Route params
A request path is matched as it is written, split on / and on nothing else.
An encoded slash (%2F, %2f) is part of its segment, never a separator:
/s/abc%2Fdef has two segments and answers routes/s/[code].tsx, and
/dublin%2Fcork has one, so it does not answer routes/[from]/[to].tsx. A
static segment of a route matches a segment that percent-decodes to it, so
/%61bout reaches routes/about.tsx, and a route whose file name is not ASCII
is reached by its percent-encoded path.
A matched route gets its params twice:
| request path | ctx.params | ctx.rawParams |
|---|---|---|
| /s/abc | { code: "abc" } | { code: "abc" } |
| /s/a%26b%20c+d | { code: "a&b c+d" } | { code: "a%26b%20c+d" } |
| /s/abc%2Fdef | { code: "abc%2Fdef" } | { code: "abc%2Fdef" } |
| /s/abc%252Fdef | { code: "abc%2Fdef" } | { code: "abc%252Fdef" } |
| /s/a%5Cb | { code: "a%5Cb" } | { code: "a%5Cb" } |
| /files/a%20b/c%2Fd (files/[...rest]) | { rest: "a b/c%2Fd" } | { rest: "a%20b/c%2Fd" } |
| /files (files/[...rest]) | {} | {} |
| /s/%E0%A4%A (malformed) | { code: "%E0%A4%A" } | { code: "%E0%A4%A" } |
ctx.paramsis each segment decoded withdecodeURIComponent, one segment at a time, except that decoding never makes a separator: an encoded slash or backslash (%2F,%2f,%5C,%5c) stays in the param as the URL wrote it, case included. A wildcard is its decoded segments joined with/, so it holds exactly as many/as the path had separators and can be split on/safely.- This is deliberate, and so is the next rule: no param is ever
.or.., and none can be read as a path that climbs./blog/..%2F..%2Fetc%2Fpasswdgivesslug: "..%2F..%2Fetc%2Fpasswd", one segment of text. - Warning: params keep
%2Fand%5Cencoded on purpose. Do not rundecodeURIComponenton a param before using it in a file path or in the URL of an upstream request: that turns..%2F..%2Fetcback into a path. %252Fis decoded once, to%2F, so%2Finctx.paramsis what both%2Fand%252Fgive.ctx.rawParamstells them apart.ctx.rawParamshas the same keys with the text exactly asctx.url.pathnamespells it, undecoded; a wildcard is its raw segments joined with/. Use it to decode by another rule:decodeURI(ctx.rawParams.code)leaves%23 %24 %26 %2B %2C %2F %3A %3B %3D %3F %40encoded and decodes the rest (%5Cincluded).- A segment with a malformed escape (
%,%zz, a cut-off UTF-8 sequence) still matches, and both objects carry that whole segment as written. Nothing throws, anddecodeURIon it will: catch that. - A segment that decodes to something holding NUL is never a param: no param route answers such a path.
- An empty segment and a trailing slash match nothing:
/about/and//aboutare not/about. - Dot segments never reach a route. The URL of a request has them resolved
before fu reads it, written out or encoded:
/files/a/../band/files/a/%2e%2e/bboth arrive as/files/b. (The matcher resolves them the same way for a direct caller, and hands none to a param.) - Both objects are
{}in a middleware untilctx.next()has resolved.
Async pages
The page component, routes/_error.tsx and routes/_app.tsx may each be an
async function:
export default async function Post(ctx: PageContext<State>) {
const post = await loadPost(ctx.params.slug);
if (!post) throw new HttpError(404);
ctx.state.pageTitle = post.title; // the shell reads this
return <article>{post.body}</article>;
}fu calls an async one itself, with what it would have been rendered with (the
page and the error page get ctx, the shell { ctx, children }), awaits it
and renders what it resolved to. The order is fixed: the page (or the error
page) settles first, then the shell is called. So whatever an async page
writes on ctx.state or ctx.head is there when the shell runs. A
synchronous page is rendered inside the tree, as always, which means after
the shell has run: a shell cannot read state that a synchronous page writes
while rendering. Write it from a handler, or make the page async.
- An async component is called outside the renderer, so it cannot use
hooks (
useState,useContext,useId, signals hooks). What it returns can: components and islands in it render as anywhere else. - A rejection is a throw: from the page it goes to the error page with the
status of an
HttpError, or 500; from the error page it falls back to the plain-text response; from the shell it is a 500 in plain text. - State survives a failure.
ctx.stateis one object for the whole request and is never reset. What an async page wrote there before it rejected (and what a handler or a synchronous page wrote before throwing) is still there when the error page and the shell run.ctx.headis reset,ctx.stateis not: an error page that must not show a half-computed title or view name overwrites it. - "Async" means declared with the
asynckeyword. Nothing else can be awaited, and nothing is dropped silently: a page, error page or shell that returns a promise without beingasync(a class whoserender()returns one included), and an async component anywhere else in the tree, fail the render with an error that names the component. An island cannot be the page, the error page or the shell, async or not: that fails too. - Known limits. A component further down the tree that returns a promise
without being
async, function or class, is the one case fu cannot see: Preact renders nothing for it. And detection is by the keyword, so a build step that compiledasyncaway would turn an async page into the "returned a promise" failure (loud, not silent); fu's own build does not.
Middleware
app.ts composes an ordered chain. Registration order is outermost first, so
the first registered runs first on the way in and unwinds last — it has the
final say on headers, including on short-circuit responses from further in.
import { App } from "@janit/fu";
const app = new App<State>();
app.use(async (ctx) => { // outermost: unwinds last
const res = await ctx.next();
res.headers.set("Content-Security-Policy", "default-src 'self'; frame-ancestors 'none'");
res.headers.set("X-Frame-Options", "DENY");
return res;
});
app.use((ctx) => // short-circuit: never calls next()
ctx.url.pathname === "/healthz"
? new Response("ok")
: ctx.next()
);
app.use((ctx) => { // populate state for everything below
ctx.state.tenant = resolveTenant(ctx.req);
return ctx.next();
});
export default app;A middleware either returns a Response (short-circuiting) or returns
ctx.next(). Await next() first to inspect or mutate the response. Throwing
propagates outward past any await ctx.next(). Pass ctx itself along, never
a copy: its fields are views onto one shared context, and { ...ctx } copies
none of them.
Middleware runs before routing, so ctx.params and ctx.rawParams are
empty inside it — match on ctx.url.pathname. That is what lets a middleware answer a request no route
exists for: redirects, /healthz, /robots.txt.
Redirects need nothing special — read state, read the URL, return a response:
export const redirects: Middleware<State> = (ctx) => {
const hit = table[ctx.url.pathname];
if (!hit) return ctx.next();
return new Response(null, { status: hit.status, headers: { location: hit.to } });
};Nothing in a request says whether fu dev or a build is serving it, and the
same middleware runs in both. So the dev server sets FU_DEV=1 in its own
environment before it starts the app, and a built server never does. Read it
for anything that must be laxer in dev — a Content-Security-Policy, say, which
has to name the HMR socket on port + 1, because a different port is a
different origin:
const dev = ctx.env.FU_DEV === "1"; // inside a middleware; ctx.env on every runtime
// The HMR client dials the host the page came from, so name that host. Check
// it first: URL keeps ";" in a host name, which would open a new directive.
const host = ctx.url.hostname;
const named = /^(\[[0-9a-f:.]+\]|[a-z0-9.-]+)$/i.test(host) ? host : "localhost";
const connectSrc = dev ? `connect-src 'self' ws://${named}:* wss://${named}:*` : "connect-src 'self'";Errors
Anything thrown by a handler, a page or a middleware is turned into a response
rather than reaching the server as an unhandled crash. So are 404 and 405.
HttpError takes a status from 400 to 599.
import { type Handlers, HttpError } from "@janit/fu";
export const handlers: Handlers<State> = {
GET(ctx) {
if (!ctx.state.session) throw new HttpError(403, "Not yours");
...
},
};HttpError takes response headers as a third argument —
new HttpError(429, "Slow down", { headers: { "retry-after": "30" } }) — and
they are sent whether or not an error page renders.
An optional routes/_error.tsx renders them, receiving ctx like any page with
ctx.error set to { status, message }. It is wrapped by routes/_app.tsx, so
error pages inherit the app's markup. Without one you get plain text.
Two things the framework does for you:
- An unexpected throw never renders its message.
ctx.error.messageis generic for it, and for a 5xx from another library; the real error goes toctx.error.causeand is logged, because a thrown error's message routinely carries connection strings and file paths. A message you wrote yourself, innew HttpError(...), is rendered at any status, 5xx included. - No failure the framework renders is cacheable. Its error responses carry
no-store, and the error page adds<meta name="robots" content="noindex">(the plain-text fallback has no such tag, and neither has a shell that owns the document). During a deploy a valid URL can 404 for a few seconds, and a shared cache would pin that. One place is not yours: everything under/_fu/belongs to the built client files. A path there that is not a file, and any method but GET and HEAD, gets a plain 404 and never reaches your routes, middleware or error page. That 404 isno-storetoo: a page left open across a deploy asks for chunks of the old build, and a cached 404 would outlive a rollback. The year-longimmutableheader goes on a client file asked for by the exact URL the build gave it (a query string allowed) and served from the asset store (200, 206 or 304), and on nothing else. No path is interpreted:/_fu/boot-abc.js/and/_fu/%62oot-abc.jsare not that URL and get the 404, and//_fu/x,/_fu%2Fx,/_FU/xand the like are not under the prefix, reach your app like any other unknown path, and come back with the headers your app gave them.
Errors from a handler or a page are caught at the route boundary and returned
through the middleware chain, so security headers and logging middleware still
see them. A middleware that throws is different: the throw propagates outward
past every await ctx.next(), so an outer middleware can catch it, and only what
nobody catches becomes an error response — at the very top, after the chain has
unwound, without the headers the middleware would have set. To refuse a request
from middleware, return the response rather than throwing.
Page metadata
ctx.head is the channel from a route to the document <head>. Middleware can
write to it too.
export const handlers = {
GET: (ctx: PageContext<State>) => {
ctx.head.title = `${ctx.params.slug} — Fresh Urquell`;
// ctx.url.origin echoes the request's Host header; a real site configures its origin.
ctx.head.canonical = `${ctx.url.origin}/blog/${ctx.params.slug}`;
ctx.head.jsonLd = { "@context": "https://schema.org", "@type": "BlogPosting" };
return null;
},
};The framework renders title, description, canonical, robots, image,
lang, arbitrary links and a JSON-LD block. An optional routes/_app.tsx
wraps the body markup and can read ctx.state.
An island is any component under islands/. It renders on the server and
hydrates on the client:
import { useSignal } from "@preact/signals";
import styles from "./counter.module.css";
export default function Counter({ start = 0 }) {
const n = useSignal(start);
return <button class={styles.badge} onClick={() => n.value++}>{n}</button>;
}Every export of an island file is an island, default or named, so one file can
hold several. Props travel to the client as JSON: strings, numbers, arrays and
plain objects cross; a function or JSX element (including JSX children) fails
the render with an error naming the prop, rather than hydrating without it.
The server renders the island with the props as the client will parse them, so
a Date is its ISO string, NaN is null and a Map is {} on both sides.
An island rendered inside another island is part of the outer one: it hydrates with it and gets no boundary of its own, so editing it in dev reloads the page rather than hot-swapping. A class component works as an island, but its state does not survive a hot swap the way hook state does. Islands hydrate independently, so one that throws is reported in the console and the rest of the page still works.
Owning the document
A routes/_app.tsx that returns <html> owns the whole document. fu writes
the doctype in front of it and nothing else: no charset, no viewport, no
lang (ctx.head.lang is for fu's own document and is not used here).
import { FuHead, FuScripts, type ShellProps } from "@janit/fu";
export default function Shell({ ctx, children }: ShellProps<State>) {
return (
<html lang={ctx.state.lang}>
<head>
<meta charset="utf-8" />
<FuHead />
</head>
<body>
{children}
<FuScripts />
</body>
</html>
);
}<FuHead /> is where fu's head tags go: the ctx.head fields that were set,
the stylesheets, the preloads and the JSON-LD block. <FuScripts /> is where
the boot script goes, usually last in <body>. Leave one out and what it
stands for is not emitted (no stylesheets, or no hydration), with one warning
in the server log; place one twice and the render fails. A shell that returns
anything else is wrapped in fu's document as before, and the two components
are ignored there.
On the error page the head is the shell's too. Before routes/_error.tsx
renders, fu clears what the failed page put in ctx.head (keeping lang and
links, which are app-wide) and gives it two defaults: a title such as
404 Not Found, and robots: "noindex". In fu's own document those are
emitted. An owning shell writes its own <title> and robots tag, so there
<FuHead /> leaves the two defaults out and emits only what the app itself
assigned to ctx.head after that reset, which in practice means from the
error page or the shell, a title or robots value included. The reset takes
everything else with it: a description, canonical, image or jsonLd
that a middleware set before calling ctx.next() is gone on the error path,
in either kind of document (a middleware that wants a field on every page,
error pages too, uses links, or sets it in the shell). What fu still
guarantees for every error response is the status and
cache-control: no-store; saying noindex on an error page is then the
shell's job:
{ctx.error && <meta name="robots" content="noindex" />}The defaults stay readable (ctx.head.title is "404 Not Found" while the
error page renders), so a shell can still use them. Assigning to a field is
what makes it the app's, whatever the value: code that copies the head onto
itself, such as Object.assign(ctx.head, { ...ctx.head }), assigns the two
defaults too, and an owning shell then emits them again.
Response status and headers
A handler or a middleware sets ctx.response.status and
ctx.response.headers and the rendered page carries them:
export const handlers = {
GET: (ctx: PageContext<State>) => {
ctx.response.status = 410;
ctx.response.headers.set("cache-control", "public, max-age=60");
return { gone: true };
},
};A Response returned by a handler ignores them, and so does every error
response: a handler that set a public cache-control and then threw cannot
make the error cacheable. A status of 400 or more is sent no-store whatever
the headers say. The status must be 200 to 599 and not 204, 205 or 304, which
cannot carry a page; anything else fails the render. set-cookie is appended,
every other header replaces.
Static files
@janit/fu/static has two middlewares: assets() reads the runtime's asset
store, so it works on celld and everywhere else; staticFiles() reads a
directory, so it needs a filesystem. Both serve from inside the middleware
chain: a middleware registered before them can answer a path itself and still
decorates what is served (security headers, say), and anything that is not a
file falls through to ctx.next(). Unlike /_fu/, which is served before the
app runs.
import { assets } from "@janit/fu/static";
import { STATIC_PATHS } from "./static-paths.gen.ts"; // your build's list
app.use(assets({
isStatic: (pathname) => STATIC_PATHS.has(pathname),
cacheControl: (pathname, url) =>
url.searchParams.has("v") ? "public, max-age=31536000, immutable" : "public, max-age=3600",
contentType: (pathname) => pathname === "/LICENSE" ? "text/plain; charset=utf-8" : null,
}));assets() answers GET and HEAD from ctx.assets (celld's ASSETS
binding, or the directory the runner and fu dev hand over). A 200, 206 or
304 from the store is passed on with cacheControl(pathname, url) put on it,
a 304 included, and with contentType(pathname) when the store sent no type
(celld sends none for an unknown extension); anything else, a miss included,
falls through. isStatic is asked first, with the raw path, so a page request
costs no lookup in the store; without it every GET is tried. store gives it
a store of its own, such as assetsFromDir(dir). On celld it needs
run_worker_first to cover those paths, or celld answers them before the
Worker is asked.
assetsFromDir(dir, { etag }) is the store over a directory that the runner
and fu dev use. It answers as celld's does, as far as an app can tell: the
file or a 304, a 404 for a miss, a 405 for another method.
import { staticFiles } from "@janit/fu/static";
app.use(staticFiles({
dir: "/srv/app/static",
cacheControl: (pathname) => pathname.startsWith("/icons/") ? "public, max-age=604800" : null,
}));staticFiles() is assetsFromDir as a middleware, reading the path in
ctx.url (so a middleware before it may rewrite it). It imports node:fs, so
it does not work on celld; an app that imports only assets() from the same
module gets none of that code in its Worker. What it and assetsFromDir
promise:
- Paths. The raw path is split on
/and each segment decoded on its own, so an encoded slash is never a separator. A segment that is empty, starts with a dot (.,.., dotfiles), holds a slash, a backslash or a NUL once decoded, or is malformed, is not served. No directory listing and noindex.html. - Symlinks are followed and their targets are not checked against
dir. Only put links you trust there. dirshould be absolute. A relative one is resolved once, against the directory the server was started from. If the result is not a directory, a warning is logged at startup and every request falls through.- Validators. A weak
ETagfrom size and modification time, andLast-Modified; a matchingIf-None-Match(which wins when both are sent) orIf-Modified-Sincegets a 304.Cache-Controlis whatevercacheControl(pathname, url)returns for a file that is served, given the decoded path; none by default. A 304 carries the sameETag,Last-ModifiedandCache-Controlas the 200 would, as RFC 9110 asks, so a cache refreshes its entry with them. - Your own ETag. The built-in tag changes whenever a file is written
again, identical bytes or not, which every image build does. An app that
knows better passes
etag: (pathname, stat) => string | null, withstatbeing{ size, mtimeMs }: return the complete header value, quotes included ('"' + hash + '"', orW/"..."for a weak one), ornullfor the built-in tag. It is asked once per served file, and its value is the one sent and the oneIf-None-Matchis compared with. Anything that is not an entity-tag, a tag with a comma in it (If-None-Matchis a comma-separated list, so it could never match), or a throw, is logged once and the built-in tag used. - Types.
Content-Typecomes from a fixed list of extensions and every response isX-Content-Type-Options: nosniff, so a file whose extension is not on the list (src/static.ts) arrives asapplication/octet-stream, a download. - No byte ranges (
Accept-Ranges: none; aRangeheader gets the whole file) and no compression. Put large media somewhere else.
Client navigation
Off unless a page asks for it. Wrap what a navigation should replace in
<Partial name="...">, in the body and, if the title and meta tags should
follow, in <head>; put data-fu-nav on <body>; and, optionally, a build id
on <html>:
<html lang="en" data-fu-build={BUILD}>
<head>
<meta charset="utf-8" />
<Partial name="head">
<title>{title}</title>
</Partial>
<FuHead />
</head>
<body data-fu-nav="on">
<Nav />
<main>
<Partial name="content">{children}</Partial>
</main>
<FuScripts />
</body>
</html>A click on a link then fetches the destination with ?fu-partial=1 (and
&__b=<build> when the page has a build id), replaces each region of the page
on screen with the region of the same name from the answer, hydrates the
islands that arrived and unmounts the ones that left. Everything outside the
regions stays as it is: an island there keeps its state.
The boot module requests the navigation chunk only when <body> carries
data-fu-nav as the page loads, alongside the island chunks. A page without
the attribute requests nothing extra and behaves as before. The value "off"
loads the chunk and holds it back: the attribute is read again at every click,
on the nearest ancestor of the link that has it, so a script can switch a
document, or one part of it, on and off.
Which clicks. A plain left click on an <a href> to the same origin over
http(s), that nobody called preventDefault on. Left to the browser: a
modified click, target other than _self, download, rel="external", a
link to a fragment of the page on screen, and every form. Forms are never
intercepted; a submit is a full load.
The server's side. The answer to a partial fetch is the ordinary page, in
full; ctx.partial is true for it, should a page want to skip work. Both
parameters are in ctx.url: a page that echoes ctx.url.search into a
canonical link or a form action should drop them. A middleware can refuse a
client from another deploy by answering with the x-fu-reload header:
import { BUILD_PARAM, BUILD_RELOAD_HEADER } from "@janit/fu";
app.use((ctx) => {
const theirs = ctx.url.searchParams.get(BUILD_PARAM);
if (!ctx.partial || !theirs || theirs === BUILD) return ctx.next();
return new Response(null, { headers: { [BUILD_RELOAD_HEADER]: "1", "cache-control": "no-store" } });
});When it will not swap. Anything unexpected ends in a full load of the
destination, which is always correct: the x-fu-reload header, an error
status, an answer that is not HTML, a data-fu-build that differs from the
page's own, a failed fetch. So does a redirect: the browser is sent to the URL
the redirect ended on (one extra request), not shown a page under the wrong
address. And so does any doubt about the regions: on either page a name used
twice, a region inside a region, a marker without its partner, or the two
pages not having the same set of names. A page on screen whose own regions are
unsound is not navigated on the client at all.
Raw HTML is trusted. Regions are delimited by comments
(<!--fu:p:name-->, <!--/fu:p-->). Text rendered through Preact cannot
contain one, but dangerouslySetInnerHTML can, and such a comment is
indistinguishable from fu's own. The integrity rules above turn most of that
into a full load; they are not a sanitiser.
Scripts. Executable scripts that arrive in a region are re-created and
run, in document order, as on a full load, every time the region is entered: a
script that registers a global listener registers it again. A classic external
script without async or defer holds back the ones after it until it has
loaded. Data scripts (application/ld+json, an import map) and nomodule
scripts are left alone. A script that must run once per document belongs
outside every Partial.
Back and Forward. fu remembers the URL of the page it last drew. A
popstate whose path or query differs from it fetches and swaps that page,
whoever made the history entry and whatever state it holds; one that differs
in the fragment only is the browser's. The app may use history.pushState and
replaceState freely: replaceState on the current entry is followed (the
page on screen is then known by its new URL, and coming back to it later draws
nothing), pushState is not, so an entry the app pushed under another path is
asked of the server when Forward reaches it, and has to be a route.
Scroll. history.scrollRestoration is left alone, so a reload keeps its
position as in any document. After a click the page is at the top, or at the
element the fragment names. For Back and Forward the position is restored
after the swap from the history entry, where fu keeps it under the key fu of
history.state, merged into whatever object the app keeps there (a state that
is not an object is left alone, and that entry gets no position).
Events, on window, with detail: { from, to }: fu:nav-start before
the fetch; fu:nav after the swap, once the islands that arrived are
hydrated; fu:nav-error, with detail.error, before every fallback to a full
load. The latest navigation wins, and one that was overtaken gets no closing
event of its own. Back to the page on screen while a fetch is pending ends
that navigation with a fu:nav whose from and to are the same.
The runtime's own entry points are hydrateIslands(manifest, markers?) in
@janit/fu/client and installNav(manifest) in @janit/fu/nav. The generated
boot module calls both; an app has no need to. hydrateIslands keeps no
record of what it hydrated, so an element must be passed to it once.
In-process tests
import { appHandler } from "@janit/fu/testing";
import { assetsFromDir } from "@janit/fu/static";
const pending: Promise<unknown>[] = [];
const handler = await appHandler("/abs/path/to/app", {
env: { API_URL: "http://api.test" }, // ctx.env; default {}
assetStore: assetsFromDir("/abs/path/to/static"), // ctx.assets; default none
});
const res = await handler(new Request("http://x/about"));
// What a single request passes goes over those defaults, as celld's would:
await handler(new Request("http://x/"), { waitUntil: (p) => pending.push(p) });The app's request handler, built from its source files and routed exactly as
the built server would. No bundler runs, so whatever runs the test loads the
sources (Deno as they are; Node strips types from .ts on its own and needs a
loader for .tsx), and islands render as plain components without their
data-island markers: a test that asserts markers or assets needs a real
build. The modules go through the runtime's module cache, so two handlers for
one app share its module-level state.
Using Effect
fu has no Effect integration and needs none: a handler returns a Promise,
and Effect runs to one. Build the runtime once per isolate, in prepare,
where env is at hand; app modules run after prepare, so they can import
it:
// lib/runtime.ts
import { Context, Effect, Layer, ManagedRuntime } from "effect";
import type { Env } from "@janit/fu";
export class Greeter extends Context.Service<Greeter, {
readonly greet: (name: string) => Effect.Effect<string>;
}>()("app/Greeter") {}
const make = (env: Env) =>
ManagedRuntime.make(Layer.succeed(Greeter, Greeter.of({
greet: (name) => Effect.succeed(`${env.GREETING ?? "Hello"}, ${name}`),
})));
export let runtime: ReturnType<typeof make>;
export function initRuntime(env: Env): void {
runtime = make(env);
}
// worker.ts
import type { Env } from "@janit/fu";
import { initRuntime } from "./lib/runtime.ts";
export function prepare(env: Env): void {
initRuntime(env);
}
// routes/index.tsx
import { Effect } from "effect";
import type { PageContext } from "@janit/fu";
import { Greeter, runtime } from "../lib/runtime.ts";
export const handlers = {
GET: (ctx: PageContext) =>
runtime.runPromise(Effect.gen(function* () {
const greeter = yield* Greeter;
return { greeting: yield* greeter.greet("world") };
})),
};
export default function Home(ctx: PageContext) {
return <h1>{(ctx.data as { greeting: string }).greeting}</h1>;
}- Errors.
runPromiserejects with the failure itself, so the framework's error handling applies: failing withHttpError, or with a tagged error carrying astatusfield, renders that status. Turn an expected failure into aResponseinside the Effect (Effect.catchTag) when the route answers with something other than the error page. A defect is a 500. - Work after the response goes through
ctx.waitUntil(runtime.runPromise(...)), as any other promise would; a fiber forked and left running is not waited for. - Finalizers do not run when the server stops. fu has no shutdown hook,
and celld stops an isolate without one, so a scoped layer is acquired and
never released. Do not rely on a release for correctness. Under
fu deveach save runsprepareagain and builds a fresh runtime, leaving the old one undisposed (seeworker.ts). - Size. Measured with
effect4.1.2, minified: a few services andEffect.genadded 135 KB to the Worker (43 KB gzipped). An island that imports Effect carries about 38 KB more (12 KB gzipped); keep Effect on the server unless an island needs it.
Effect 4.1.2 runs under the runner on Deno, Node and Bun, under fu dev, and
under celld bundled and with no_bundle, islands included. Effect's own code
looks for node:async_hooks through process.getBuiltinModule and does
without it where there is none.
What works
Routing (static, dynamic and wildcard, on the raw segments of the path),
middleware with typed shared state, page metadata, a root shell that may own
the whole document, async pages, status and headers per page, static files, SSR, island
hydration, signals, CSS and CSS Modules with composes, native CSS nesting and
@layer, opt-in client navigation, and HMR that preserves component state.
Editing an island hot-swaps its markup without losing hook state. Editing CSS swaps the stylesheet in place. Editing a route rebuilds the server.
Architecture
Two layers with a hard boundary. The core is bundler-agnostic — it consumes only a route manifest and an asset list, both plain data:
type RouteManifest = Record<string, () => Promise<RouteModule>>;
type Assets = {
js: { href: string }[];
css: { href: string }[];
preload?: { href: string }[]; // what every page preloads
islands?: Record<string, string | string[]>; // island file -> its chunk's URL,
// or [its chunk, ...the chunks that one imports statically]
};The core's whole contract with a runtime is one function,
(request, { env, waitUntil, assets }) => Promise<Response>, and it never
learns whether celld or the runner called it.
Everything bundler-specific lives in the drivers (src/build.ts, src/dev.ts),
the glue they share (src/driver.ts: locating the runtime modules, scanning a
project, the generated modules, the rolldown option sets) and the rolldown
plugins (src/plugins.ts). The runner (src/serve.ts) knows srvx and nothing
of the bundler. The same core ran unchanged under a Vite driver during
prototyping, so swapping the build layer stays cheap.
Routing compares path segments, with no pattern engine: a route with no param
is matched by string equality against the decoded path, and a param route
whose segment count or first segment cannot fit is skipped before anything is
allocated. With 16 routes on Deno a static hit is ~55 ns, a dynamic one
~500 ns and a miss ~1500 ns (URLPattern.exec, which did this until 0.5.2,
cost ~1900 ns for the dynamic hit).
See the design doc for the full rationale and the undocumented traps this implementation encodes.
Tests
deno task testdeno test over the whole workspace, no browser needed. The framework suite is written against the
failure modes this framework actually hit, so each one guards a real regression:
| area | what it pins down |
|---|---|
| router | static beats dynamic beats wildcard, ties broken by the earliest literal segment, never by file order; wildcards span segments and match their own base path; an encoded slash never separates segments, against a param, a wildcard or a static segment; params decode per segment, but %2F and %5C stay encoded, so decoding never makes a separator, and rawParams are the URL's text; no param is a dot segment, written out or encoded; a malformed escape matches and is handed over as written; NUL never reaches a param; a non-ASCII static route matches its percent-encoded request; empty segments, a trailing slash and dot segments match as they did before the matcher was rewritten; matching is case-sensitive; a path of 8000 segments, valid or not, is matched in linear time |
| middleware | outer unwinds last and decorates inner short-circuits; next() twice rejects; throws propagate |
| render | head escaping; JSON-LD cannot close its own <script>; 404 vs 405, Allow, HEAD and OPTIONS; islands get a marker |
| errors | a 500 never leaks its message; error responses are uncacheable; a broken error page falls back; an owning shell gets none of fu's error defaults in its head |
| async | an async page, error page and shell are awaited, page first; a promise nobody can await fails the render, naming the component |
| build | a missing file under /_fu/ is no-store while a real one stays immutable; a page preloads exactly the chunks its islands import statically; the Worker is one file exporting only handlers, with no node: import of fu's, and runs nothing of the app before prepare |
| assets | a store's file gets the app's headers, a 304 too; a miss or a write falls through; the store's immutable headers are copied; /_fu/ exact hits only |
| serve | the runner hands the Worker the environment and ASSETS; a body reaches it; a waitUntil failure is logged, not fatal, and close waits for work in flight; a bad PORT is refused by name, an empty HOST is none |
| document | an owning shell is recognised behind comments and a doctype in any case, in linear time; a marker placed twice fails; the marker token never reaches a client |
| static | traversal, dotfiles and encoded separators are refused before any filesystem call; a matching etag beats a stale date; an app's own etag is the one compared; a response nobody reads holds no file open |
| navigation | which clicks are taken; unsound or mismatched regions mean a full load; the latest navigation wins at every await; history and scroll for clicks, Back and Forward; an app's replaceState is followed |
| plugins | composes keeps every class name; CSS output changes with content; the JSX transform never touches rolldown's runtime; the package self-alias |
| driver | the server entry imports only the optional files that exist; worker.ts exports are carried, prepare is called once and retried after a failure, and what celld cannot take is refused |
| dev | the HMR socket admits only the dev server's own pages, not another site or a rebound name; a patch is written and sent before it is reported delivered; a rebuild that does not load leaves the last one serving; SIGTERM and SIGINT end a real dev server with code 0 and free both ports |
| cli | flags without a command mean dev; a port is decimal and leaves room for the HMR socket; each flag is refused where it does not apply |
Two of these were found by writing the suite, not before it: ctx.next() called
twice resumed at the wrong depth, and a middleware throwing synchronously
escaped the chain entirely instead of rejecting.
Known gaps
- HMR works only from the machine running
fu dev. With--host 0.0.0.0the pages are reachable across the network, but the HMR client always dialslocalhost, and the socket admits only the dev server's own pages, which is what keeps a DNS-rebinding page from reading your source. A page opened from another machine renders and hydrates, but does not hot-swap. - Nothing is compressed: not the HTML, not the client files (celld negotiates no encodings, so pre-compressed copies would be dead bytes). Put a compressing proxy in front.
- The dev server's memory grows with every save: each rebuild of the server is loaded as a new module, and a runtime never frees one it has loaded. Restart it in a long session.
fu devruns the Worker on Node, Deno or Bun, resolving packages as that runtime does; the build resolves them as a Worker would (workerd,worker). A package that differs between the two behaves as the build has it only in the build.celld devover.outputis the runtime-true check.- The package exports more than the documented API. The supported surface is
App,HttpError,statusText,FuHead,FuScripts,Partial, the navigation protocol constants (PARTIAL_PARAM,BUILD_PARAM,BUILD_RELOAD_HEADER,NAV_ATTR,BUILD_ATTR), the typesHandlers,Middleware,PageContext,ResponseOverrideandShellProps(the props ofroutes/_app.tsx:{ ctx, children }),Env,AssetStoreandRequestExtra, and the subpaths@janit/fu/static(assets,assetsFromDir,staticFiles),@janit/fu/serve(serveWorker) and@janit/fu/testing(appHandler). The rest (createHandler,compose, the router, the./build,./dev,./render,./router,./plugins,./client,./nav,./errorsand./clisubpaths) is what the drivers and tests use, and may change in any release;createHandleris the function behind the(request, extra)contract above, and that contract is what is supported. - Client navigation has been driven in Chromium only. It does not manage
focus or announce a navigation to a screen reader, does not use view
transitions, and remembers the scroll position of the window only, not of
an inner scrolling element. It writes that position with
history.replaceStateeach time scrolling settles; WebKit refuses more than 100 history writes in 30 seconds, shared with the app's own, and a refused write is dropped silently. Partialis also the name of TypeScript'sPartial<T>. A file that imports the component and needs the type imports it under another name:import { Partial as Region } from "@janit/fu".- The dev server finds routes and islands once, at start. Editing one rebuilds, but a newly added file needs a restart.
- Adding or removing a hook in an island breaks hook order during HMR. It does not crash, but needs a manual refresh.
- An editor that truncates or renames a file on save can be read mid-save. The island then keeps its previous code (with a console warning) rather than crashing, and that save is lost: save again to apply it.
- Naming an anonymous
export default () => {}island shifts source positions, so that one module's sourcemap is dropped rather than left wrong. ctx.rawParamsis raw as far as the URL of theRequestis: URL parsing has already resolved dot segments (encoded ones too), escaped what cannot stand in a path, and turned\into/. An escape that was sent is not changed, in spelling or in case.- No sourcemaps in dev, no error overlay, no prerendering, no per-route CSS splitting.
- No per-directory
_middleware.ts. Middleware is registered programmatically inapp.ts; scope it with a path check. (Measured against a real app: nested middleware had zero uses across 43 middleware.) - No shutdown hook: nothing tells the app the server is stopping, so what
prepareopened (a connection pool, an Effect runtime's scoped layers) is never closed by the app. The runner waits forwaitUntilwork, then exits. - Deliberately absent: streaming SSR, nested layouts, wrappers for Durable
Objects, KV, queues and cron (they are celld's, reached through
ctx.envandworker.ts).
Status
Alpha, and built on deliberately unstable ground: Preact 11 is days old, celld
is beta, and rolldown's devMode is marked "not ready for public usage".
That instability is an accepted trade.
MIT.
