@lunora/nuxt 1.0.0-alpha.4 → 1.0.0-alpha.41

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -59,14 +59,23 @@ export default defineNuxtConfig({
 });
 ```
 
-Add `exports.cloudflare.ts` to the project root so the `ShardDO` Durable Object
-class is exported from the emitted worker entry:
+Add a `worker.ts` wrapper at the project root and point `wrangler.jsonc`'s `main`
+at it, so the `ShardDO` Durable Object class is exported from the deployed worker.
+Nitro's `cloudflare_module` output exports only the SSR handler, so `main` must
+point at the wrapper — not the raw `.output/server/index.mjs` — or `wrangler deploy`
+fails on the missing DO class:
 
 ```ts
-// exports.cloudflare.ts
+// worker.ts
+export { default } from "./.output/server/index.mjs";
 export { ShardDO } from "./lunora/server";
 ```
 
+```jsonc
+// wrangler.jsonc
+{ "main": "worker.ts" }
+```
+
 `lunora/server.ts` is your built Lunora app (`defineApp().build()`) — its default
 export is the worker (a `fetch` entrypoint), and it re-exports `ShardDO`. The
 module aliases the `#lunora/app` virtual to it (configurable via the `lunora.appEntry`
@@ -88,8 +97,8 @@ option, default `~/lunora/server`) and serves it at the `/_lunora/**` route
   and forwards to your app's `fetch`. A missing Cloudflare runtime answers a clear 500.
 - **`#lunora/app` alias**: points the route's worker import at your app entry,
   forwarded into the Nitro server bundle via `nuxt.options.alias`.
-- **`ShardDO`** rides to the worker entry through your root `exports.cloudflare.ts`
-  (the `cloudflare_module` preset appends its exports).
+- **`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`.
 
 ## Verify before deploy
 
@@ -102,11 +111,12 @@ Single-worker composition rides on two Nitro behaviours that vary across version
    subscriptions never connect while RPC does, Nitro is normalising the upgrade
    response and `/_lunora/ws` needs a deploy-boundary handoff instead of the H3
    route return.
-2. **`exports.cloudflare.ts` hook.** The `cloudflare_module` preset must append
-   this file's exports onto the worker entry. If `wrangler deploy` fails with
-   "ShardDO class not exported", your Nitro version may use a different hook
-   (`nitro.cloudflare.additionalModules`, or a `rollupConfig` output export). The
-   module `warn()`s when the file is missing but can't verify the hook fires.
+2. **`worker.ts` wrapper.** `wrangler.jsonc`'s `main` must point at a root
+   `worker.ts` that re-exports Nitro's SSR handler _and_ `ShardDO` — Nitro's
+   `cloudflare_module` output exports only the SSR handler. If `wrangler deploy`
+   fails with "ShardDO class not exported", check that `main` points at the
+   wrapper and that it re-exports `ShardDO`. The module `warn()`s when
+   `worker.ts` is missing but can't verify wrangler's `main` points at it.
 
 ## Server data-loading
 
@@ -115,6 +125,30 @@ Single-worker composition rides on two Nitro behaviours that vary across version
 reactive-loader handoff. Safe to import from a Nitro server route (no WebSocket,
 no browser globals).
 
+## Feature flags
+
+`@lunora/nuxt` ships no flag composable — Nuxt _is_ Vue, so 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`](https://www.npmjs.com/package/@lunora/vue) directly in a
+component for live updates over the WebSocket. Requires
+[`@lunora/flags`](https://www.npmjs.com/package/@lunora/flags) wired in
+`lunora/flags.ts`.
+
+```vue
+<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>
+```
+
 ## Supported Node.js Versions
 
 Libraries in this ecosystem make the best effort to track [Node.js' release schedule](https://github.com/nodejs/release#release-schedule).

package/dist/module.d.ts

@@ -0,0 +1,24 @@
+import { defineNuxtModule } from '@nuxt/kit';
+/** Options for the `@lunora/nuxt` module (configurable under the `lunora` key in `nuxt.config`). */
+interface ModuleOptions {
+  /**
+   * Module specifier of the Lunora app entry — its default export is the built
+   * worker (`defineApp().build()` / `createWorker(...)`) and it re-exports
+   * `ShardDO`. Aliased to the `#lunora/app` virtual the server route imports.
+   */
+  appEntry: string;
+  /** URL prefix Lunora realtime is mounted at. */
+  prefix: string;
+}
+/**
+ * Return type of `defineNuxtModule<ModuleOptions>({...})` — the value overload of
+ * `defineNuxtModule` (the one taking a definition), extracted structurally so the
+ * default export has a locally-nameable type under `isolatedDeclarations` without
+ * importing `NuxtModule` from `@nuxt/schema` (not a resolvable dependency here).
+ */
+type LunoraNuxtModule = typeof defineNuxtModule<ModuleOptions> extends {
+  (definition: infer _Definition): infer Result;
+  (): unknown;
+} ? Result : never;
+declare const lunoraNuxtModule: LunoraNuxtModule;
+export { ModuleOptions, lunoraNuxtModule as default };

package/dist/module.js

@@ -0,0 +1,72 @@
+import { existsSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { defineNuxtModule, createResolver, addServerHandler, useLogger } from '@nuxt/kit';
+
+const resolveTildePath = (specifier, rootDirectory, sourceDirectory) => {
+  if (specifier.startsWith("~~/")) {
+    return join(rootDirectory, specifier.slice(3));
+  }
+  if (specifier.startsWith("~/")) {
+    return join(sourceDirectory, specifier.slice(2));
+  }
+  if (specifier.startsWith("./") || specifier.startsWith("../")) {
+    return join(rootDirectory, specifier);
+  }
+  return specifier;
+};
+
+const JS_EXTENSION_SUFFIX = /\.js$/;
+const lunoraTsSourceResolver = (rootDirectory) => {
+  const lunoraDirectory = join(rootDirectory, "lunora");
+  return {
+    name: "lunora:nitro-ts-source-resolve",
+    resolveId: {
+      handler(source, importer) {
+        if (!source.endsWith(".js")) {
+          return void 0;
+        }
+        let absolute;
+        if (source.startsWith("#lunora/")) {
+          absolute = join(lunoraDirectory, source.slice("#lunora/".length));
+        } else if (source.startsWith(".") && importer !== void 0) {
+          absolute = resolve(dirname(importer), source);
+        }
+        if (absolute === void 0) {
+          return void 0;
+        }
+        const tsSource = absolute.replace(JS_EXTENSION_SUFFIX, ".ts");
+        return existsSync(tsSource) ? tsSource : void 0;
+      },
+      order: "pre"
+    }
+  };
+};
+const lunoraNuxtModule = defineNuxtModule({
+  defaults: {
+    appEntry: "~/lunora/server",
+    prefix: "/_lunora"
+  },
+  meta: {
+    configKey: "lunora",
+    name: "@lunora/nuxt"
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    nuxt.options.alias["#lunora/app"] = resolveTildePath(options.appEntry, nuxt.options.rootDir, nuxt.options.srcDir);
+    nuxt.hook("nitro:config", (nitroConfig) => {
+      const plugins = [...nitroConfig.rollupConfig?.plugins ?? [], lunoraTsSourceResolver(nuxt.options.rootDir)];
+      nitroConfig.rollupConfig = { ...nitroConfig.rollupConfig, plugins };
+    });
+    addServerHandler({
+      handler: resolver.resolve("./runtime/server/lunora"),
+      route: `${options.prefix}/**`
+    });
+    if (!existsSync(join(nuxt.options.rootDir, "worker.ts"))) {
+      useLogger("@lunora/nuxt").warn(
+        'missing worker.ts at the project root — add a wrapper that re-exports Nitro\'s handler and `ShardDO` (`export { default } from "./.output/server/index.mjs"; export { ShardDO } from "./lunora/server";`) and point wrangler\'s `main` at it, so the SHARD Durable Object is exported from the deployed worker.'
+      );
+    }
+  }
+});
+
+export { lunoraNuxtModule as default };

package/dist/module.json

@@ -1,9 +1,5 @@
 {
   "configKey": "lunora",
   "name": "@lunora/nuxt",
-  "version": "1.0.0-alpha.3",
-  "builder": {
-    "@nuxt/module-builder": "1.0.2",
-    "unbuild": "unknown"
-  }
-}
+  "version": "1.0.0-alpha.40"
+}

package/dist/runtime/cloudflare.d.ts

@@ -0,0 +1,36 @@
+import { ExecutionContextLike } from '@lunora/runtime';
+export type { ExecutionContextLike } from '@lunora/runtime';
+/** The `{ env, context|ctx }` payload Nitro attaches for the Cloudflare runtime. */
+interface CloudflareEventBag {
+  context?: ExecutionContextLike;
+  ctx?: ExecutionContextLike;
+  env?: Record<string, unknown>;
+}
+/**
+ * Structural view of the bits of an H3 event the resolver reads. Both legacy
+ * (`context.cloudflare`) and current (`req.runtime.cloudflare`) shapes are
+ * optional so a real H3 `H3Event` is assignable here.
+ */
+interface H3EventLike {
+  context?: {
+    cloudflare?: CloudflareEventBag;
+  };
+  req?: {
+    runtime?: {
+      cloudflare?: CloudflareEventBag;
+    };
+  };
+}
+/** Resolved Cloudflare runtime for one request: the bindings `env` and the optional `ExecutionContext`. */
+interface ResolvedCloudflare {
+  ctx?: ExecutionContextLike;
+  env?: Record<string, unknown>;
+}
+/**
+ * Pull the Cloudflare `env` + `ExecutionContext` off a Nitro/H3 event, checking
+ * the legacy `event.context.cloudflare` shape first (present under
+ * `nitro-cloudflare-dev` in dev) and the newer `event.req.runtime.cloudflare`
+ * shape second. Returns `{}` when neither is present.
+ */
+declare const resolveCloudflare: (event: H3EventLike) => ResolvedCloudflare;
+export { type H3EventLike, type ResolvedCloudflare, resolveCloudflare };

package/dist/runtime/cloudflare.js

@@ -1,3 +1,5 @@
+import '@lunora/runtime';
+
 const resolveCloudflare = (event) => {
   const fromContext = event.context?.cloudflare;
   if (fromContext?.env) {
@@ -9,4 +11,5 @@ const resolveCloudflare = (event) => {
   }
   return {};
 };
+
 export { resolveCloudflare };

package/dist/runtime/h3-request.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Resolve the inbound web `Request` from an H3 event across the h3 v1 → v2 break.
+ *
+ * v1 exposes `toWebRequest(event)`; the v2 web-standards rewrite removed it and
+ * carries the web `Request` directly as `event.req`. The `@lunora/nuxt` peer is
+ * `h3: "^1.15.0"` (v1 — what Nuxt 4 / Nitro 2 run today); the v2 `event.req`
+ * branch is forward-compat for when a stable h3 v2 ships and the peer widens. We
+ * feature-detect `toWebRequest` at runtime rather than importing it statically —
+ * a named `import { toWebRequest }` would throw at module-eval under v2 (missing export).
+ *
+ * Kept as a pure helper (the `h3` namespace + event in, a `Request` out) so both
+ * branches are unit-tested without booting Nitro or installing a second h3 major.
+ */
+interface H3RequestNamespace {
+  toWebRequest?: unknown;
+}
+declare const resolveWebRequest: (h3: H3RequestNamespace, event: unknown) => Request;
+export { type H3RequestNamespace, resolveWebRequest };

package/dist/runtime/h3-request.js

@@ -0,0 +1,3 @@
+const resolveWebRequest = (h3, event) => typeof h3.toWebRequest === "function" ? h3.toWebRequest(event) : event.req;
+
+export { resolveWebRequest };

package/dist/runtime/handler.d.ts

@@ -0,0 +1,19 @@
+import { ExecutionContextLike } from '@lunora/runtime';
+export { NOOP_EXECUTION_CONTEXT } from '@lunora/runtime';
+/**
+ * Structural view of the Lunora worker the route delegates to — just the
+ * `fetch` entrypoint. Both `createWorker(...)` and the generated
+ * `defineApp().build()` app satisfy it (a `ComposedApp` is a superset). Declared
+ * locally so `@lunora/nuxt` doesn't hard-depend on `@lunora/runtime`'s worker type.
+ */
+interface LunoraWorkerLike {
+  fetch: (request: Request, env: unknown, context: ExecutionContextLike) => Promise<Response> | Response;
+}
+/**
+ * Forward one inbound request to the Lunora worker. `env` must be the Cloudflare
+ * bindings (carrying the `SHARD` Durable Object namespace); when it is missing
+ * the Cloudflare runtime wasn't available (e.g. a non-CF preview), so we answer
+ * a clear 500 rather than handing the worker an `undefined` env.
+ */
+declare const delegateToLunora: (worker: LunoraWorkerLike, request: Request, env: Record<string, unknown> | undefined, context?: ExecutionContextLike) => Promise<Response>;
+export { type LunoraWorkerLike, delegateToLunora };

package/dist/runtime/handler.js

@@ -1,9 +1,6 @@
-const NOOP_EXECUTION_CONTEXT = {
-  passThroughOnException: () => {
-  },
-  waitUntil: () => {
-  }
-};
+import { NOOP_EXECUTION_CONTEXT } from '@lunora/runtime';
+export { NOOP_EXECUTION_CONTEXT } from '@lunora/runtime';
+
 const delegateToLunora = async (worker, request, env, context) => {
   if (!env) {
     return Response.json(
@@ -18,4 +15,5 @@ const delegateToLunora = async (worker, request, env, context) => {
   }
   return worker.fetch(request, env, context ?? NOOP_EXECUTION_CONTEXT);
 };
-export { delegateToLunora, NOOP_EXECUTION_CONTEXT };
+
+export { delegateToLunora };

package/dist/runtime/server/lunora.d.ts

@@ -0,0 +1,93 @@
+import { QueryObject } from 'ufo';
+import { Hooks } from 'crossws';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import 'node:stream';
+interface NodeEventContext {
+  req: IncomingMessage & {
+    originalUrl?: string;
+  };
+  res: ServerResponse;
+}
+interface WebEventContext {
+  request?: Request;
+  url?: URL;
+}
+declare class H3Event<_RequestT extends EventHandlerRequest = EventHandlerRequest> implements Pick<FetchEvent, "respondWith"> {
+  "__is_event__": boolean;
+  node: NodeEventContext;
+  web?: WebEventContext;
+  context: H3EventContext;
+  _method?: HTTPMethod;
+  _path?: string;
+  _headers?: Headers;
+  _requestBody?: BodyInit;
+  _handled: boolean;
+  _onBeforeResponseCalled: boolean | undefined;
+  _onAfterResponseCalled: boolean | undefined;
+  constructor(req: IncomingMessage, res: ServerResponse);
+  get method(): HTTPMethod;
+  get path(): string;
+  get headers(): Headers;
+  get handled(): boolean;
+  respondWith(response: Response | PromiseLike<Response>): Promise<void>;
+  toString(): string;
+  toJSON(): string;
+  /** @deprecated Please use `event.node.req` instead. */
+  get req(): IncomingMessage & {
+    originalUrl?: string;
+  };
+  /** @deprecated Please use `event.node.res` instead. */
+  get res(): ServerResponse<IncomingMessage>;
+}
+type SessionDataT = Record<string, any>;
+type SessionData<T extends SessionDataT = SessionDataT> = T;
+declare const getSessionPromise: unique symbol;
+interface Session<T extends SessionDataT = SessionDataT> {
+  id: string;
+  createdAt: number;
+  data: SessionData<T>;
+  [getSessionPromise]?: Promise<Session<T>>;
+}
+type RouterMethod = Lowercase<HTTPMethod>;
+interface RouteNode {
+  handlers: Partial<Record<RouterMethod | "all", EventHandler>>;
+  path: string;
+}
+type HTTPMethod = "GET" | "HEAD" | "PATCH" | "POST" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE";
+interface H3EventContext extends Record<string, any> {
+  params?: Record<string, string>;
+  /**
+   * Matched router Node
+   *
+   * @experimental The object structure may change in non-major version.
+   */
+  matchedRoute?: RouteNode;
+  sessions?: Record<string, Session>;
+  clientAddress?: string;
+}
+type EventHandlerResponse<T = any> = T | Promise<T>;
+interface EventHandlerRequest {
+  body?: any;
+  query?: QueryObject;
+  routerParams?: Record<string, string>;
+}
+type MaybePromise<T> = T | Promise<T>;
+type EventHandlerResolver = (path: string) => MaybePromise<undefined | {
+  route?: string;
+  handler: EventHandler;
+}>;
+interface EventHandler<Request extends EventHandlerRequest = EventHandlerRequest, Response extends EventHandlerResponse = EventHandlerResponse> {
+  __is_handler__?: true;
+  __resolve__?: EventHandlerResolver;
+  __websocket__?: Partial<Hooks>;
+  (event: H3Event<Request>): Response;
+}
+/**
+ * Forward `/_lunora/**` to the Lunora worker. We reconstruct a Web `Request`
+ * from the H3 event (Lunora speaks the Web Fetch contract — RPC bodies and the
+ * WebSocket `Upgrade` handshake), resolve the Cloudflare `env`/`ExecutionContext`
+ * off the event, and return the worker's `Response` verbatim (H3 streams it,
+ * including a `101 Switching Protocols` upgrade with its `webSocket`).
+ */
+declare const lunoraEventHandler: EventHandler;
+export { lunoraEventHandler as default };

package/dist/runtime/server/lunora.js

@@ -1,9 +1,13 @@
-import { defineEventHandler, toWebRequest } from "h3";
-import lunoraApp from "#lunora/app";
-import { resolveCloudflare } from "../cloudflare.js";
-import { delegateToLunora } from "../handler.js";
-export default defineEventHandler(async (event) => {
+import * as h3 from 'h3';
+import lunoraApp from '#lunora/app';
+import { resolveCloudflare } from '../cloudflare.js';
+import { resolveWebRequest } from '../h3-request.js';
+import { delegateToLunora } from '../handler.js';
+
+const lunoraEventHandler = h3.defineEventHandler(async (event) => {
   const { ctx, env } = resolveCloudflare(event);
-  const request = toWebRequest(event);
+  const request = resolveWebRequest(h3, event);
   return delegateToLunora(lunoraApp, request, env, ctx);
 });
+
+export { lunoraEventHandler as default };

package/dist/server.d.ts

@@ -0,0 +1 @@
+export { type ArgsOf, type AuthLike, type FunctionReference, type HeadersSource, type Preloaded, type ReturnOf, type ServerClientOptions, type ServerSession, createServerClient, deserializePreloaded, getServerSession, preloadQuery, preloadedQueryResult, serializePreloaded } from '@lunora/client/ssr';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/nuxt",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.41",
   "description": "Nuxt module for Lunora — single-worker composition (mounts /_lunora/* into Nitro) plus reactive-loader server helpers",
   "keywords": [
     "cloudflare",
@@ -33,17 +33,17 @@
   ],
   "type": "module",
   "sideEffects": false,
-  "main": "./dist/module.mjs",
-  "module": "./dist/module.mjs",
-  "types": "./dist/types.d.mts",
+  "main": "./dist/module.js",
+  "module": "./dist/module.js",
+  "types": "./dist/module.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/types.d.mts",
-      "import": "./dist/module.mjs"
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
     },
     "./server": {
-      "types": "./dist/server.d.mts",
-      "import": "./dist/server.mjs"
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
     },
     "./package.json": "./package.json"
   },
@@ -51,11 +51,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.3",
-    "@nuxt/kit": "^4.0.0"
+    "@lunora/client": "1.0.0-alpha.27",
+    "@lunora/runtime": "1.0.0-alpha.36",
+    "@nuxt/kit": "^4.4.8"
   },
   "peerDependencies": {
-    "h3": "^1.0.0",
+    "h3": "^1.15.0",
     "nuxt": "^4.0.0"
   },
   "peerDependenciesMeta": {

package/dist/module.d.mts

@@ -1,9 +0,0 @@
-import * as nuxt_schema from 'nuxt/schema';
-
-interface ModuleOptions {
-    appEntry: string;
-    prefix: string;
-}
-declare const _default: nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
-
-export { _default as default };

package/dist/module.mjs

@@ -1,29 +0,0 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { defineNuxtModule, createResolver, addServerHandler, useLogger } from '@nuxt/kit';
-
-const module$1 = defineNuxtModule({
-  defaults: {
-    appEntry: "~/lunora/server",
-    prefix: "/_lunora"
-  },
-  meta: {
-    configKey: "lunora",
-    name: "@lunora/nuxt"
-  },
-  setup(options, nuxt) {
-    const resolver = createResolver(import.meta.url);
-    nuxt.options.alias["#lunora/app"] = options.appEntry;
-    addServerHandler({
-      handler: resolver.resolve("./runtime/server/lunora"),
-      route: `${options.prefix}/**`
-    });
-    if (!existsSync(join(nuxt.options.rootDir, "exports.cloudflare.ts"))) {
-      useLogger("@lunora/nuxt").warn(
-        'missing exports.cloudflare.ts at the project root \u2014 add `export { ShardDO } from "./lunora/server";` so the SHARD Durable Object is exported from the worker.'
-      );
-    }
-  }
-});
-
-export { module$1 as default };

package/dist/server.d.mts

@@ -1 +0,0 @@
-export { ArgsOf, AuthLike, FunctionReference, HeadersSource, Preloaded, ReturnOf, ServerClientOptions, ServerSession, createServerClient, deserializePreloaded, getServerSession, preloadQuery, preloadedQueryResult, serializePreloaded } from '@lunora/client/ssr';

package/dist/types.d.mts

@@ -1,7 +0,0 @@
-import type { NuxtModule } from '@nuxt/schema'
-
-import type { default as Module } from './module.mjs'
-
-export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
-
-export { default } from './module.mjs'