@lunora/nuxt

@lunora/nuxt runs Lunora and Nuxt as a single Cloudflare Worker. Instead of Lunora owning the Cloudflare worker entry (the two-worker split other adapters use), it is mounted inside Nitro: the module registers a server route at /_lunora/** that forwards every Lunora RPC, WebSocket upgrade, and admin request to your Lunora app in-process. One wrangler.jsonc, one deploy, a same-origin client.

Install

pnpm add @lunora/nuxt

nuxt (^4.0.0) is an optional peer dependency; the host app supplies the Nuxt runtime. h3 is also an optional peer (^1.15.0); see Deploy notes below.

Setup

export default defineNuxtConfig({
    modules: ["@lunora/nuxt"],
    nitro: { preset: "cloudflare_module" },
});

export { default } from "./.output/server/index.mjs";
export { ShardDO } from "./lunora/server";

{ "main": "worker.ts" }

Options

Configurable under the lunora key in nuxt.config.ts.

How it works

• The route (addServerHandler at <prefix>/**): reconstructs a Web Request from the H3 event, resolves the Cloudflare env/ExecutionContext off it (tolerating both event.context.cloudflare and event.req.runtime.cloudflare), and forwards to your app's fetch. A missing Cloudflare runtime answers a clear 500.
• The #lunora/app alias: points the route's worker import at your app entry (options.appEntry), forwarded into the Nitro server bundle via nuxt.options.alias.
• ShardDO rides to the deployed worker through your root worker.ts wrapper (wrangler.jsonc's main), which re-exports Nitro's SSR handler and ShardDO; Nitro's cloudflare_module output exports only the SSR handler.

Server data-loading — @lunora/nuxt/server

Re-exports the framework-neutral SSR contract from @lunora/client/ssr (createServerClient, preloadQuery, serializePreloaded, deserializePreloaded, preloadedQueryResult, getServerSession, plus the ArgsOf / AuthLike / FunctionReference / HeadersSource / Preloaded / ReturnOf / ServerClientOptions / ServerSession types) for the reactive-loader handoff. Opens no WebSocket and touches no browser globals, so it is safe to import from a Nitro server route.

import { createServerClient, preloadQuery } from "@lunora/nuxt/server";

import { api } from "./lunora/_generated/api";

// Per request — never reuse a client across requests (token leakage).
const client = createServerClient({ url: process.env.LUNORA_URL!, token });
const preloaded = await preloadQuery(client, api.posts.list, {});

Hand the serializable preloaded value to a client component and seed it with @lunora/vue's hydratePreloaded. Nuxt is Vue, so the Vue adapter's composables (useQuery, useMutation, hydratePreloaded) are the reactive layer here; @lunora/nuxt only owns the server-side composition.

Feature flags

@lunora/nuxt ships no flag composable of its own. Since Nuxt is Vue, read ctx.flags server-side (a Nitro route, a function, or a reactive loader) and pass the resolved value down, or call useFlag / useFlags from @lunora/vue directly in a component for live updates over the WebSocket. Requires @lunora/flags wired in lunora/flags.ts.

<script setup lang="ts">
import { useFlag } from "@lunora/vue";

// Live over the Lunora WS — holds `false` until the server resolves it.
const newHero = useFlag("homepage-hero", false);
</script>

<template>
    <NewHero v-if="newHero" />
    <ClassicHero v-else />
</template>

Deploy notes