--- name: lunora-quickstart description: Creates a new Lunora project or adds Lunora to an existing app, then gets the first schema + query/mutation round-trip running. Use when the user asks to "start a Lunora app", "add Lunora to my Vite/Next/Nuxt/SvelteKit/Astro app", runs `lunora init` (`--vite`, `-t`, `--here`, `--add`), needs the client provider wired (`LunoraClient` + `LunoraProvider`), or is running `lunora dev` for the first time (background mode, `lunora dev status`/`logs`/ `stop`, `VITE_LUNORA_URL`). --- # Lunora Quickstart Get a working Lunora project with one live query/mutation round-trip. Skip this skill when `lunora/` already exists (just build, and run `lunora codegen` after edits) or when the task is only auth (`lunora-setup-auth`). ## Workflow 1. New project: `lunora init <name> --vite <framework>` or `-t <template>`. Existing app: `lunora init --here`. 2. `lunora codegen` to generate `lunora/_generated/`. 3. Start the dev server in the background (`lunora dev --background`). 4. Write or adapt a query + mutation and use them from a component. 5. `lunora verify` (wrangler config + codegen dry-run + `tsc --noEmit`) passes, and the client re-renders live after a mutation. ## Path 1: new project ```bash lunora init my-app --vite react cd my-app pnpm install ``` Two scaffold paths take different flags. `--vite <framework>` applies the Lunora layer over the official create-vite base. Use it for a plain SPA: `react` (the default), `vue`, `solid`, `svelte`, or `vanilla` (overlay-only, not in the picker). `-t react|vue|solid|svelte` is accepted as an alias for the same overlay. `-t` / `--template <type>` fetches a whole-project template from `gh:anolilab/lunora/templates/<type>`: | `-t` value | Stack | | ----------------------------- | ---------------------------------------------------------------- | | `next` | Next.js App Router (OpenNext) + a standalone Lunora worker | | `vinext` | Next.js App Router on Vite (vinext), one worker (experimental) | | `vinext-pages` | Next.js Pages Router on Vite (vinext), one worker (experimental) | | `tanstack-start-react` | TanStack Start (React), SSR with live-loader routes | | `tanstack-start-solid` | TanStack Start (Solid) | | `tanstack-start-react-rspack` | TanStack Start (React) on Rsbuild, one worker | | `rspack-react` | React SPA on Rsbuild (`@lunora/rspack`) | | `solid-v2` | Solid 2.0 SPA (`@solidjs/web`, `vite-plugin-solid` 3) | | `astro` | Astro, Lunora composed into the adapter worker | | `sveltekit` | SvelteKit, Lunora composed into the adapter worker | | `nuxt` | Nuxt (Vue), Lunora mounted in Nitro | | `analog` | AnalogJS (Angular), Lunora mounted in Nitro | | `expo` | React Native (Expo) app + a Lunora worker | | `standalone` | Worker-only backend, no frontend | There is no `vite` template value; `-t vite` errors. Solid 2.0 is a template rather than an overlay because create-vite's Solid base is still 1.x, so `--vite solid` stays on Solid 1.x. In a non-interactive shell, `init` errors unless it gets a name and a framework (or `--yes`, which takes the React overlay). As an agent, pass `--vite` or `-t` explicitly; if the user stated no preference, use `--vite react`. Other flags: ```bash lunora init my-app --vite react --ci github # add a deploy pipeline (or --ci gitlab) lunora init my-app -t next --add auth,email # add capabilities without prompting lunora init my-app --vite react --yes # skip the interactive auth/email offer lunora init my-app --vite react --dry-run # walk every step, write nothing ``` `--add` takes a comma-separated list of `ai | auth | auth-ui | backup | browser | cloudflare-access | crons | email | flags | hyperdrive | payment | presence | queue | storage | workflow`. `--ref <branch|tag|commit>` pins the template source (e.g. `--ref alpha`); `--from <dir>` copies from a local templates root. ## Path 2: add Lunora to an existing app ```bash lunora init --here ``` This detects the framework from `package.json`, scaffolds `lunora/schema.ts` and `lunora/messages.ts` (skipped if a schema exists), and patches or creates the Vite config with the `lunora()` plugin. SvelteKit, Nuxt and Astro wire Lunora through their server entry instead, so their Vite config is left alone. It then prints framework-specific next steps: the packages to install, the provider to mount, and how to compose the worker. Follow those; the CLI does not edit framework-owned files. Templates and `--vite` overlays map `#lunora/*` to `./lunora/*` in `package.json` `imports`, which is why their function files import `#lunora/_generated/server.js`. A `--here` project has no such mapping; its starter uses the relative `./_generated/server`. Match whichever the project already uses. ### Client provider Create the `LunoraClient` once at module scope (not inside a component, or every render opens a new socket) and wrap the app in the framework provider: ```tsx // src/client/main.tsx import { LunoraProvider } from "@lunora/react"; import { LunoraClient } from "lunorash/client"; import { StrictMode } from "react"; import { createRoot } from "react-dom/client"; import { App } from "./App"; // @cloudflare/vite-plugin serves the Worker on the same origin as Vite. const url = (import.meta.env.VITE_LUNORA_URL as string | undefined) ?? globalThis.location.origin; const client = new LunoraClient({ url }); createRoot(document.querySelector("#root")!).render( <StrictMode> <LunoraProvider client={client}> <App /> </LunoraProvider> </StrictMode>, ); ``` `LunoraClient` is also exported by `@lunora/client`. Other adapters: `@lunora/vue`, `@lunora/solid`, `@lunora/svelte`, `@lunora/angular` (`provideLunora` / `injectLunoraClient`), and `@lunora/react-native` (`createLunoraClient`, re-exporting `@lunora/react`). `@lunora/astro` and `@lunora/nuxt` mount Lunora server-side. `VITE_LUNORA_URL` is optional; the same-origin default is right for local dev. ## First function `lunora/schema.ts`: ```ts import { defineSchema, defineTable, v } from "lunorash/server"; export default defineSchema({ todos: defineTable({ text: v.string(), done: v.boolean(), createdAt: v.number(), }).index("by_creation", ["createdAt"]), }); ``` `lunora/todos.ts`: ```ts import { mutation, query, v } from "#lunora/_generated/server.js"; export const list = query.query(async ({ ctx }) => ctx.db.query("todos").withIndex("by_creation").collect()); export const add = mutation .input({ text: v.string().max(4096) }) .mutation(async ({ ctx, args }) => ctx.db.insert("todos", { text: args.text, done: false, createdAt: Date.now() })); ``` Run `lunora codegen`, then call it from a component. Argument and return types are inferred from the generated `api`, so no casts are needed: ```tsx import { useMutation, useQuery } from "@lunora/react"; import { api } from "../../lunora/_generated/api"; export const Todos = () => { const todos = useQuery(api.todos.list, {}); const { mutate: add, pending } = useMutation(api.todos.add); return ( <div> <button disabled={pending} onClick={() => add({ text: "New todo" })}> Add </button> {todos?.map((todo) => ( <div key={todo._id}>{todo.text}</div> ))} </div> ); }; ``` `useQuery` returns `undefined` while loading, then re-renders whenever a mutation changes the queried rows. A function in a folder nests in `api`: `lunora/billing/invoices.ts` is `api.billing.invoices.*`. ## Dev server `lunora dev` runs the worker (behind Vite via `@cloudflare/vite-plugin` in Vite projects), codegen-on-save, and the embedded Studio at `/__lunora`. It does not exit on its own. - User at the keyboard: ask them to run `lunora dev` in a terminal. - Agent: run `lunora dev --background`. It detaches, waits until the server answers, prints `Dev server running at <url> (pid <n>)`, and exits. When an AI agent is detected (Claude Code, Cursor, Codex, …), plain `lunora dev` does this automatically with JSON logs; `LUNORA_AGENT_MODE=0` opts out. Avoid a bare foreground `lunora dev` in your own shell, since it blocks until killed. ```bash lunora dev status --json # url, pid, uptime, logFile lunora dev logs --lines 50 # tail .lunora/dev.log lunora dev stop # idempotent ``` A second `lunora dev` reports the running instance instead of starting another (`.lunora/dev.json` is the lockfile). `GET /_lunora/status` returns `{"ok":true}` once the worker is up. Vite defaults to `http://localhost:5173`. `lunora dev --tunnel` shares the worker on a public `*.trycloudflare.com` URL (needs `cloudflared`). ## Shipping ```bash lunora doctor # preflight: SHARD DO binding, placeholder D1 ids, .dev.vars secrets, container exports lunora deploy # codegen + schema-drift gate + wrangler deploy ``` Use `lunora-deploy` for bindings, secrets and environments. ## Next steps - Auth: `lunora-setup-auth`. - Add-ons: `lunora add <feature>` (e.g. `email`, `storage`, `crons`, `presence`; `lunora registry list` for all). Mail, storage and scheduling have their own skills: `lunora-setup-mail`, `lunora-setup-storage`, `lunora-setup-scheduler`. - Schema and function rules: `lunora-functions`. Schema changes on live data: `lunora-migration-helper`.