JSPM – @lunora/runtime@1.0.0-alpha.23

Package Exports

@lunora/runtime
@lunora/runtime/package.json

Readme

Lunora Worker runtime: the RPC router, shard resolver, and query coordinator

^{Daniel Bannert's open source work is supported by the community on GitHub Sponsors}

The Worker entry layer for Lunora. createWorker(options) returns a Cloudflare module Worker ({ fetch, scheduled, serverQuery }) that decodes the Lunora RPC envelope, routes each call to the right shard Durable Object, forwards WebSocket upgrades, and fans cross-shard reads out through the query coordinator. It also exports the shard resolver, the QueryCoordinator, and the secure-by-default HTTP edge (security headers, CORS, CSRF).

Most apps don't import this package directly — codegen emits a worker entry that calls createWorker for you. Reach for @lunora/runtime when you build a custom entrypoint, an add-on route, or your own transport.

Part of the Lunora framework — a type-safe, real-time backend on Cloudflare Workers + Durable Objects with a Vite-first DX.

Install

npm install @lunora/runtime

yarn add @lunora/runtime

pnpm add @lunora/runtime

Usage

import type { LunoraWorker } from "@lunora/runtime";
import { createWorker } from "@lunora/runtime";

import { ShardDO } from "./shard";

interface Env {
    SHARD: DurableObjectNamespace;
}

// Bindings only exist per request, so build the worker lazily off `env` and
// reuse it for the isolate's lifetime.
let worker: LunoraWorker | null = null;

export default {
    fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
        worker ??= createWorker({ shardDO: env.SHARD }); // shardDO is the one required option

        return worker.fetch(request, env, ctx);
    },
};

// Re-export the Durable Object so wrangler can bind it.
export { ShardDO };

shardDO is the one required option — the DurableObjectNamespace bound to your ShardDO. Everything else is opt-in: a queryCoordinator for cross-shard fan-out, resolveIdentity for auth, security for the HTTP edge, crons / backupCron for the scheduled handler, and the admin introspectors the Studio reads. createWorker returns { fetch, scheduled, serverQuery }; wire scheduled too if you use crons or the built-in backup. See the docs for the full options table.

This README covers the basics. For the full API, options, and guides, see the documentation.

Workers Cache

When cache: { enabled: true } is present in wrangler.jsonc and compatibility_date >= "2026-05-01", the runtime forwards the Worker's ExecutionContext.cache into action handlers as ctx.cache. This lets you purge cache by tag from HTTP action handlers:

export const refreshProducts = action.action(async ({ ctx }) => {
    if (!ctx.cache) {
        throw new Error("Workers Cache is not enabled in wrangler.jsonc");
    }

    await ctx.cache.purge({ tags: ["products"] });
    return { ok: true };
});

The ctx.cache binding is only available in action handlers (not query/mutation), because actions run in the Worker while queries/mutations run inside the Durable Object. Cache header declarations on httpRoute (.cacheControl(), .cacheTag(), .vary()) are attached by @lunora/server before the response leaves the handler.

@lunora/do — the ShardDO / SessionDO Durable Objects this runtime routes to.
@lunora/server — defines the queries, mutations, and actions the runtime executes.
@lunora/d1 — backs .global() tables used by the query coordinator.

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js' release schedule. Here's a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guidelines.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

Made with ❤️ at Anolilab

This is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. Anolilab is a Development and AI Studio. Contact us at hello@anolilab.com if you need any help with these technologies or just want to say hi!

License

The Lunora runtime package is open-sourced software licensed under the FSL-1.1-Apache-2.0.

@lunora/runtime