Last updated:
Lunora is not a web framework. It is a reactive backend that any meta-framework plugs into (TanStack Start, React Router, SolidStart, SvelteKit, Nuxt, Astro), composed into a single Cloudflare Worker. You keep your framework's routing, rendering, and developer experience; Lunora adds type-safe data and live loaders.
One worker, two dispatch flows
A Lunora worker is created with createWorker(...), which accepts an optional
httpRouter: any object shaped like { fetch(request, env?, ctx?) }. Every
meta-framework's server-side rendering (SSR) handler has exactly that shape, so you mount it as the
httpRouter and Lunora dispatches by path:
import { createWorker, type ExecutionContextLike, type LunoraWorker } from "lunorash/runtime";
import { ssrHandler } from "./framework-entry"; // your framework's SSR fetch handler
// The Durable Object class is exported for wrangler; `shardDO` takes its namespace binding.
export { ShardDO } from "lunorash/do";
let worker: LunoraWorker | undefined;
export default {
fetch(request: Request, env: Env, ctx: ExecutionContextLike): Promise<Response> {
worker ??= createWorker({
httpRouter: ssrHandler, // pages / API / SSR loaders
shardDO: env.SHARD, // the SHARD Durable Object namespace from wrangler.jsonc
// auth (serves /api/auth/*), …
});
return worker.fetch(request, env, ctx);
},
};The worker resolves each request in this order:
/api/auth/*→@lunora/auth- explicit routes → webhooks / callbacks
/_lunora/rpc→ query / mutation RPC/_lunora/ws→ subscriptions / deltas/_lunora/admin/*→ studio / observability (any other/_lunora/*path is a 404, never the app)httpRouter.fetch→ your meta-framework's SSR handler (everything else)
Lunora realtime is mounted under the reserved /_lunora/* namespace, so it
never collides with your framework's routes. Pages and API go to your framework;
queries, mutations, and subscriptions go to /_lunora/*. A 500 from your SSR
handler does not take down the realtime endpoints.
Shipped: a composeWorker({ httpRouter, ...lunoraOptions }) helper, a thin
wrapper over createWorker so templates read cleanly, plus an in-process
serverQuery fast-path so an SSR loader can call Lunora directly inside the
same worker instead of round-tripping /_lunora/rpc. serverQuery still makes
the worker-to-Durable-Object hop (dispatch lives inside the DO, so a worker-side
createCaller is impossible), but it drops the self-fetch loopback while
keeping byte-identical identity and row-level security (RLS) semantics.
Mount Lunora inside your framework
The section above is the Lunora-owns-the-entry direction (httpRouter /
withLunora). The inverse, where your framework owns the entry and you mount
Lunora's realtime plane as a middleware, is the common case for web-standard
HTTP frameworks like Hono, Nitro / h3,
and Elysia. For these you do not need a per-framework
adapter package: the entire seam is one shared helper, createLunoraHandler.
import { createLunoraHandler } from "lunorash/runtime";createLunoraHandler(options?) returns a framework-neutral
(request, env, ctx?) => Response that owns the reserved /_lunora/* namespace
(/_lunora/rpc, /_lunora/ws, /_lunora/admin/*). Mount it under /_lunora/*
in your router; everything else stays your framework's. shardDO defaults to the
conventional env.SHARD binding, so the common case needs no options.
// Hono — c.req.raw is a Web Request; c.env carries the bindings.
import { Hono } from "hono";
import { createLunoraHandler } from "lunorash/runtime";
const lunora = createLunoraHandler();
const app = new Hono<{ Bindings: Env }>();
app.use("/_lunora/*", (c) => lunora(c.req.raw, c.env, c.executionCtx));
app.get("/", (c) => c.text("hi")); // your routes, 100% plain Hono
export default app;// Nitro / h3 — env + ExecutionContext live on the Cloudflare runtime accessor.
import { createLunoraHandler } from "lunorash/runtime";
const lunora = createLunoraHandler();
// server/routes/_lunora/[...].ts
export default defineEventHandler((event) => {
const { ctx, env } = event.context.cloudflare;
return lunora(toWebRequest(event), env, ctx);
});// Elysia — ctx.request is a Web Request.
import { createLunoraHandler } from "lunorash/runtime";
const lunora = createLunoraHandler();
app.all("/_lunora/*", ({ request }) => lunora(request, env));Every host satisfies the same four-part contract, which is all the helper needs:
- a Web
Request, - the Cloudflare
env(carrying theSHARDDurable Object namespace), - an
ExecutionContextwhen the runtime supplies one (omit it and a no-op is used), and - WebSocket pass-through: the
101 Switching ProtocolsupgradeResponse(with itswebSocket) is returned verbatim, so the framework streams the socket through unchanged.
For bindings that only exist at request time, pass an (env) => options factory
instead of a fixed object:
const lunora = createLunoraHandler((env) => ({ shardDO: env.MY_SHARD, auth }));Your framework must run on Cloudflare Workers. Durable Object bindings (env.SHARD) exist only inside the Workers runtime, so this seam works for
web-standard frameworks deployed to Workers (Hono natively, Nitro's cloudflare-module preset, Elysia on Workers, …). Node-only servers (Express, Fastify,
Koa) cannot host the realtime plane in-process; point their client at a separately-deployed Lunora worker instead.
Why no @lunora/hono / @lunora/nitro / @lunora/elysia packages? Because there is nothing framework-specific left to package: each integration is
the one-/two-line bridge above over the shared createLunoraHandler. A dedicated package is only warranted when a framework needs real build/module wiring
beyond a fetch bridge (e.g. Nuxt, which registers a server handler, a #lunora/app virtual, and re-exports ShardDO from a root worker.ts wrapper;
hence @lunora/nuxt exists).
The per-framework matrix
How a framework composes with Lunora depends on who owns the worker entry. This mirrors void's class-a/b/c model.
| Class | Frameworks | Composition strategy | Status |
|---|---|---|---|
| A: Vite-native, Lunora owns the entry | TanStack Start, React Router (Vite), SolidStart | createWorker({ httpRouter: <framework SSR handler> }) directly in the worker entry. Cleanest tier; in-process serverQuery available here. | TanStack Start proven; React Router + SolidStart templated, in progress |
| B: own CF adapter, hook-injection | SvelteKit, Astro | The framework builds its own server and emits its handler as an importable module; a composed entry wraps that output with withFrameworkWorker (realtime under /_lunora/*) and it ships as the one deploy entry. | SvelteKit proven end-to-end; Astro wired on the same mechanism |
| C: non-CF or SSR-less | static / SPA | No SSR loaders. Ship the client adapter plus a standalone Lunora worker (the current default for SPA apps). Data is still live; it hydrates client-side instead of from the HTML. | shipped |
Class A is the cleanest: Lunora owns the Cloudflare worker entry, so the
framework's SSR handler goes straight into httpRouter. Class B frameworks bundle
their own worker, so Lunora is injected into their server entry rather than
fighting their build (withFrameworkWorker-style wrapping). Class C has no
SSR loaders, so there's nothing to make live on the server. The client adapter
still gives you live queries; they hydrate on the client.
What class B requires from the build toolchain: the framework's Cloudflare
adapter must emit its SSR handler as an importable module: a { fetch }
object or a bare fetch function reachable from a normal import. That's true
for @sveltejs/adapter-cloudflare and @astrojs/cloudflare; it is not true
for Nitro's cloudflare_module preset, which is why Nuxt is not class B (below).
How class-B composition deploys one worker (proven with Astro). The
wrinkle class-B frameworks introduce is that their Cloudflare adapter owns the
build. @sveltejs/adapter-cloudflare overwrites whatever the wrangler
main field points at with its own generated worker, so main cannot point
at the template's src/worker.ts (the build would clobber it). Here is the
working wiring, proven by a real lunora init -t sveltekit, then vite build,
then wrangler deploy --dry-run:
- Point wrangler
mainat the adapter's own default output (.svelte-kit/cloudflare/_worker.js), so the adapter writes there and never touchessrc/worker.ts. - Keep
src/worker.tsas thebuildFrameworkWorkerwrapper (codegen's generated app method, backed bywithFrameworkWorkerfrom@lunora/runtime): it imports that emitted handler, mounts Lunora realtime under/_lunora/*, and re-exportsShardDO. lunora deploypassessrc/worker.tsas the positional deploy entry, which overridesmain, so the single worker Cloudflare runs is the composed one. (lunora deployrunsvite buildfirst, so the adapter output exists.)
The dry-run confirms a single worker exporting ShardDO with both the SHARD
(Durable Object) and ASSETS bindings: no second worker, no class-C fallback.
Astro composes the same way, but with src/server.ts rather than
src/worker.ts, and its adapter takes the opposite route from SvelteKit's.
@astrojs/cloudflare exports its SSR handler as an importable function
(handle from @astrojs/cloudflare/handler), so the composed entry imports
handle directly and hands it to buildFrameworkWorker, and wrangler's main
points straight at that source file. The adapter's embedded
@cloudflare/vite-plugin then builds it into dist/server/entry.mjs and writes
a .wrangler/deploy/config.json redirect — main is never clobbered, it is
redirected.
That redirect carries no_bundle: true, which is why the file must not be
called src/worker.ts: lunora deploy treats that exact path as SvelteKit's
shape and passes it positionally, and a positional under no_bundle is uploaded
as the worker verbatim — raw TypeScript, exit 0, and a worker that cannot
parse.
Nuxt/Nitro: not class B, use @lunora/nuxt. Nitro does not expose its emitted fetch handler as an importable virtual module: there is no
#nitro-cloudflare-handler or equivalent specifier in any documented Nitro API. buildFrameworkWorker/withFrameworkWorker composition, which needs
exactly that importable handler, is therefore not achievable for Nuxt through any supported mechanism. Nuxt gets single-worker composition a different way
instead: the @lunora/nuxt module mounts Lunora inside Nitro as a server route (addServerHandler at /_lunora/**, a
#lunora/app alias, and a root worker.ts wrapper re-exporting ShardDO) rather than wrapping Nitro's output from the outside. If you'd rather not use
that module, the Nuxt guide also documents a two-worker split as a fallback.
Client adapters
The browser SDK, @lunora/client, is framework-neutral: transport,
subscriptions, the offline queue, delta-merge, and reconnect have zero framework
code. Each adapter is a thin idiomatic layer on top, and every adapter exposes the
same handoff: a live useQuery (or equivalent), an optimistic useMutation (or
equivalent), a provider/context, and the preloaded-hydration primitive that seeds
an SSR value into a live subscription.
| Adapter | Idiom | Status |
|---|---|---|
@lunora/react | hooks + context | shipped |
@lunora/solid | signals / resources | preview |
@lunora/svelte | stores ($store) / runes | preview |
@lunora/vue | composables (ref / reactive) | preview |
@lunora/angular | signals + DI | preview |
The Solid, Svelte, Vue, and Angular adapter packages exist and expose the same hydrate-then-subscribe handoff under their idiom, but they are preview: not yet proven end-to-end against a running app. The React adapter is the only one proven through the full live-loader path (see Manual end-to-end verification).
For React today, the preloaded-hydration primitive is usePreloadedQuery (see
Reactive loaders). The Solid/Svelte/Vue
adapters expose hydratePreloaded under their idiom's name; Angular's
hydratePreloaded (@lunora/angular) follows the same shape.
Adapter API notes (alpha)
The adapters share one contract across frameworks. A couple of differences are worth calling out for anyone who tracked the earlier previews:
useMutationhandle is uniform:{ data, error, pending, mutate, reset }in React/Solid/Vue (Svelte exposes the same fields as stores). Multi-query optimistic updates are passed per call via theoptimisticUpdateoption onmutate; the Vue adapter no longer ships a boundwithOptimisticUpdate(...)handle (React keeps it). Usemutate(args, { optimisticUpdate })everywhere instead.- Provider accessor is
useLunorain React/Solid/Vue (Svelte uses the idiomaticgetLunoraClient). The Vue adapter's earlieruseLunoraClientname is gone; useuseLunora. - Actions have their own primitive, named per idiom:
useAction(React/Vue),createAction(Solid),action(Svelte),runAction(Angular). The first four return the same handle shape as the mutation one withcallin place ofmutate—{ data, error, pending, call, reset }, witherrortypedError | undefinedeverywhere; Angular's is a plain function, matching itsmutate, because Angular models writes as calls rather than reactive handles. All five are narrower than their mutation counterpart: per-call options are the sharedActionCallOptions({ shardKey, signal }) only, with nooptimistic/optimisticUpdate. An optimistic update patches the subscription cache on the assumption a write will land, and an action is not a write — it runs in the Worker, may call a third party, and has no declared effect on any query. - One lifecycle contract for
data/error, shared by the four handle adapters and enforced by thecreateCallRunnerthey all build on: both track the LATEST invocation rather than the last to settle, a success clearserror, a failure leaves the previousdatain place, andreset()clears both without cancelling an in-flight call.
Scaffolding
Scaffold a new project wired for your framework with lunora init:
lunora init my-app -t tanstack-start-react # class A — proven end-to-end
lunora init my-app --vite react # React SPA (create-vite overlay) — the default
lunora init my-app -t standalone # worker-only, no frontendlunora init -t tanstack-start-react is fully wired: it mounts the framework SSR
handler as the worker's httpRouter and sets up the @lunora/react provider in
src/routes/__root.tsx. The scaffold has no live loader route, so add one from
Reactive loaders. lunora init -t sveltekit is proven
end-to-end; its src/worker.ts, wrangler.jsonc, and lunora deploy compose
into a single worker (verified through vite build then wrangler deploy --dry-run,
exporting ShardDO with the SHARD and ASSETS bindings). Templates for
solid-v2, tanstack-start-solid, nuxt, and astro exist
alongside their adapters and are wired on the same composition seam. They are preview:
scaffoldable, not yet each smoke-proven end-to-end.
To add Lunora to an existing meta-framework app, the in-place patcher
lunora init --here detects your framework from package.json, classifies it
(A/B/C), patches your Vite config where applicable, scaffolds lunora/ (schema +
a sample query/mutation) idempotently, and prints per-framework next steps:
the right @lunora/<adapter> to install plus the worker composition to wire
(httpRouter for class A, hook-injection for class B). The lunora/ scaffold and
the config patch are applied automatically; the provider mount and worker
composition live in framework-owned files, so the CLI prints precise steps for
those rather than guessing.
Vite composition
Under Vite, the Lunora plugin stacks alongside your framework's plugin so a single
worker is emitted. Pass cloudflare: false to let the framework supply its own
Cloudflare/SSR build while the Lunora plugins (codegen, studio, wrangler
validate/reconcile) run beside it:
// vite.config.ts
import { lunora } from "@lunora/vite";
export default defineConfig({
plugins: [
frameworkPlugin(), // your framework's Vite plugin
lunora({ cloudflare: false }), // codegen + studio + wrangler reconcile, no CF takeover
],
});Framework auto-detection from package.json and full one-worker emit for class-A
frameworks are in progress.