@lunora/vite is a Vite plugin factory. A single lunora() call wires up
codegen, wrangler validation, the error overlay, and the Cloudflare Vite
plugin so vite dev runs your Worker locally with full HMR.
Installation
Run the following command in the app root:
pnpm add -D @lunora/viteThe plugin declares vite (^6.1.0 || ^7.0.0 || ^8.0.0) and @lunora/studio as peer dependencies, so install them in the app as well.
Usage
Add lunora() to the plugins array in vite.config.ts:
// vite.config.ts
import { lunora } from "@lunora/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [react(), lunora()],
});Options
| Option | Default | Purpose |
|---|---|---|
schemaDir | "lunora" | Directory containing schema.ts + function files |
apiSpec | "openapi" | API spec emitted into _generated/: "openapi"/"openrpc"/"both"/"none" |
target | "cloudflare" | Deploy target the emitted ctx.* surface is tailored to; defaults to target in lunora.config.* |
studio | true | Serve the Lunora studio at /__lunora during dev, or false to skip |
cloudflare | true | Pass options to @cloudflare/vite-plugin, or false to skip |
overlay | true | Inject @visulima/vite-overlay for runtime errors; false to skip, or an options object to forward |
validateWrangler | true | Cross-check wrangler.jsonc bindings against the schema |
allowUnauthenticatedShardAccess | false | Let the composed class-A worker serve a client-named non-default shard / fan-out without an authorizeShard callback |
shard | {} | Shard DO config baked into the composed class-A entry: cdc, reactiveCache, maxRelationKeys, relationExistsPushDown |
projectRoot | process.cwd() | Override for monorepo setups |
The plugin has no lazy-functions option. Set codegen: { lazyFunctions: true }
in lunora.config.ts instead: codegen reads it on every run, so the plugin and
lunora codegen/prepare/verify/build/deploy all generate the same
registry. LUNORA_LAZY_FUNCTIONS=1 or true also enables lazy imports for one
run; lunora dev --lazy-functions sets it for its bundler child process.
Generated files always land in <schemaDir>/_generated.
shard — class-A only
A class-A app (TanStack Start, vinext, React Router, SolidStart) has no
hand-written worker entry, so it never calls the generated defineApp() builder
and has no createShardDO(config) of its own. shard is how it configures the
shard Durable Object instead — the plugin bakes it into the entry it composes:
lunora({
shard: {
cdc: true, // record a post-image to __cdc_log on every write
reactiveCache: true, // or { maxEntries, maxBytes } to tune the caps
},
});Ignored for class B/C, which pass their own config through defineApp() (or
createShardDO) in their worker entry — an explicit argument there is
unaffected by this option.
Codegen lifecycle
The plugin watches <schemaDir>/**/*.ts. On any change it parses the
schema with ts-morph, regenerates _generated/*.ts, and the Vite module
graph picks up the new types, so your editor sees the change before you can
swap windows.
Wrangler validator
Compares the table tier modifiers in your schema with durable_objects.bindings,
d1_databases, and r2_buckets in wrangler.jsonc. Reports missing
bindings as Vite errors before they explode at deploy.
Studio
During dev the plugin mounts the Lunora studio at /__lunora so you can browse
your schema, data, logs, and advisors without leaving the dev server. Set
studio: false to turn it off.
Error overlay
The plugin injects @visulima/vite-overlay
so runtime and codegen failures show up in the browser instead of only the
terminal. On top of it Lunora registers solution finders that recognise
framework-specific failures and render a fix hint in the overlay:
- a missing or non-object-literal
defineSchema(...) - a reserved or duplicate table name
- an invalid
.jurisdiction(...)value - a non-literal
uniqueindex flag - a container/workflow class that isn't re-exported by your worker entry
- a row that exceeds the storage engine's size limit (
lunora-row-too-big) - runtime unique-constraint and optimistic-concurrency (
ConflictError) conflicts
Pass an options object to forward overlay configuration, including your own
solutionFinders, which run alongside Lunora's (each error resolves to the
highest-priority finder that recognises it):
lunora({
overlay: {
solutionFinders: [myCustomFinder],
},
});Set overlay: false to disable it entirely.
Dev-server state & AI agents
While vite dev runs, the plugin registers the server in .lunora/dev.json
(URL, PID, start time; per-checkout, gitignored, secret-free) and removes the
record on shutdown. That record is what lets lunora dev status, lunora dev stop, and lunora dev logs manage a Vite-based project, and what
lunora dev --background blocks on before reporting the URL and PID. An AI
agent can then start, health-check (GET /_lunora/status on the worker), and
stop your dev server without parsing terminal output or leaking zombie
processes.
When an AI agent is detected (or LUNORA_LOG_JSON=1 is set), the worker's
structured log events pass through as raw single-line JSON instead of the
pretty [lunora] terminal rendering, so machine consumers can parse them
directly. Set LUNORA_AGENT_MODE=0 to opt out of agent detection.
API
lunora(options?)
Type: (options?: LunoraPluginOptions) => LunoraPlugins
Returns the flat array of Vite plugins described above. Pass the options from the Options table. Throws when lazyFunctions is passed (set codegen.lazyFunctions in lunora.config instead) or when the resolved target has no command-line toolchain, such as node.
LunoraPluginOptions
Type: interface
The object accepted by lunora(). Each field is listed in the Options table.
LunoraShardConfig
Type: interface
The shard option. Fields are cdc?: boolean, reactiveCache?: boolean | { maxEntries?: number; maxBytes?: number }, maxRelationKeys?: number, and relationExistsPushDown?: "always" | "auto" | "never". Applies only to class-A apps; see shard.
CloudflarePluginOptions
Type: Record<string, unknown>
Options forwarded to @cloudflare/vite-plugin. Passed as the cloudflare option.
OverlayPluginOptions
Type: NonNullable<Parameters<typeof errorOverlayPlugin>[0]>
Options forwarded to @visulima/vite-overlay. Passed as the overlay option. Lunora prepends its own solution finders to solutionFinders.
lunoraSolutionFinder and lunoraSolutionFinders
Type: SolutionFinder and ReadonlyArray<SolutionFinder>
The solution finders that cover the failures listed in Error overlay. lunoraSolutionFinder is the single finder with priority 100. lunoraSolutionFinders is the array the plugin registers.
SolutionFinder and Solution
Type: type
SolutionFinder is one entry of the overlay's solutionFinders array. Solution is the value a finder's handle method resolves to.
STUDIO_PATH and buildStudioUrl
Type: const
STUDIO_PATH is the mount path of the Studio, /__lunora. buildStudioUrl({ address?, base?, resolvedLocal? }) returns the full Studio URL for a running dev server.
withWorkerStartupHint, WORKER_STARTUP_HINT, and augmentWorkerStartupError
Type: (plugins) => Plugin[], string, and (error: unknown) => unknown
The helpers lunora() uses to add the Worker-entry startup hint to the Cloudflare plugin hooks. Call them only when you compose the Cloudflare plugin yourself with cloudflare: false.
LUNORA_API_UPDATED_EVENT
Type: const ("lunora:api-updated")
The custom HMR event codegen sends on the client environment's hot channel after a successful run.
LUNORA_WORKER_VIRTUAL_ID
Type: const (string)
The virtual module id of the composed Worker entry for class-A frameworks. A template points its wrangler.jsonc main at it.
VERSION
Type: const (string)
The @lunora/vite version read from the package manifest.
Plugin factories
The other exports, such as codegenPlugin, devStatePlugin, studioPlugin, and wranglerValidatorPlugin, are the plugins that lunora() returns. Call lunora() rather than composing them yourself.