## Model Context Protocol This documentation is also served over MCP at https://lunora.sh/mcp — an unauthenticated Streamable HTTP endpoint exposing `lunora_search_docs`, `lunora_get_doc` and `lunora_list_docs`. Prefer it over crawling these pages: search returns the relevant sections directly. claude mcp add --transport http lunora-docs https://lunora.sh/mcp Or run `lunora mcp install` inside a project to wire it into your editor alongside that project's own Lunora server. # Lunora - [Overview](/docs/overview): The Convex-style real-time backend that runs on your own Cloudflare account — typed end to end, live by default, ~$0 at idle. - [Getting started](/docs/getting-started): Scaffold a Lunora app and run the dev loop in under a minute. - [Quickstarts](/docs/quickstarts): Every starting point Lunora scaffolds — pick your framework, run one command, and get a live backend wired to it. - **Concepts** - [Schema](/docs/concepts/schema): Declarative tables, validators, indexes and sharding. - [Validation](/docs/concepts/validation): The v.* validators that type your columns and parse query / mutation / action inputs and outputs end to end. - [Data types](/docs/concepts/data-types): The value types a Lunora document can hold, how each is stored, and which ones need the wire codec to survive JSON. - [Document IDs](/docs/concepts/document-ids): Every row carries an _id and a _creationTime — how they are minted, how v.id types a reference, and what an id does and does not guarantee. - [Relations](/docs/concepts/relations): Modeling many-to-one and one-to-many relationships with the one / many relation descriptors, foreign-key columns and indexed reads. - [Constraints](/docs/concepts/constraints): Unique, non-null and foreign-key integrity declared on the schema and enforced at write time. - [Queries & mutations](/docs/concepts/queries-mutations): query / mutation / action — what each is for and how ctx is shaped. - [Function context](/docs/concepts/function-context): The ctx object passed to every query, mutation, and action — and what each kind is allowed to do with it. - [Real-time](/docs/concepts/realtime): How subscriptions, deltas, and hibernation fit together. - [Offline-first](/docs/concepts/offline-first): Persist reads and writes to disk so the app boots, renders, and accepts edits with no network. - [Local-first sync](/docs/concepts/local-first): Shapes, the poke diff protocol, and custom mutators — the Zero-class sync engine. - **Functions** - [Actions](/docs/concepts/actions): Non-deterministic functions for external APIs and side effects — the action builder and its ActionCtx. - [Internal functions](/docs/concepts/internal-functions): internalQuery / internalMutation / internalAction — server-only functions never exposed to the client. - [HTTP endpoints](/docs/concepts/http-endpoints): Public HTTP routes with httpAction and the Hono-based httpRouter. - [Public REST API](/docs/concepts/rest-api): Publish a query, mutation, or action as a plain REST endpoint with .expose({ rest: true }) — default-closed, routed through the procedure so auth, RLS, and validators still apply, and described by the generated OpenAPI. - [Server-side & non-reactive clients](/docs/concepts/server-clients): Calling a Lunora deployment without a live subscription — from SSR loaders, scripts, other languages, or plain HTTP. - [Caching](/docs/concepts/caching): Edge caching with Cloudflare Workers Cache — declarative headers on HTTP routes and programmatic cache purging from actions. - [Middleware](/docs/concepts/middleware): Compose cross-cutting concerns — auth checks, rate limiting, logging — and augment ctx for downstream handlers. - [Components](/docs/concepts/components): Package backend features — tables, functions, and context — as an installable unit that cannot collide with the app that installs it. - [Scheduling](/docs/concepts/scheduling): Defer follow-up work with ctx.scheduler.runAfter / runAt, and run recurring jobs via Cron Triggers. - [Push notifications](/docs/concepts/notifications): Configure defineNotify in lunora/notify.ts for Web Push + FCM, register browser subscriptions, and send via ctx.notify / ctx.push from an action. - [Error handling](/docs/concepts/error-handling): Throwing inside handlers, how errors travel to the client, and reading error state without losing optimistic safety. - [Runtime & bundling](/docs/concepts/runtime): Everything runs on the Workers runtime — what that means for Node APIs, dependencies, and the 10 MB bundle you have to fit into. - **Data** - [Indexes](/docs/concepts/indexes): Declare B-tree indexes on tables and query them with withIndex — every filtered read should hit one. - [Filtering](/docs/concepts/filtering): .filter() is a JavaScript predicate applied after rows are loaded — when to use it, and when to reach for an index instead. - [Pagination](/docs/concepts/pagination): Keyset pagination with .paginate(options) — page through a query and build an infinite list on the client. - [Full-text search](/docs/concepts/search): Declare a search index on a table and run relevance-ordered full-text queries. - [Vector search](/docs/concepts/vector-search): Typed Vectorize indexes on ctx.vectors — automatic write sync, similarity search, and RAG with embeddings. - [Geospatial](/docs/concepts/geospatial): Store lat/lng points with v.geoPoint, index them with .geoIndex, and answer "places near me" and bounding-box reads with withGeoIndex. - [File storage](/docs/concepts/file-storage): Typed R2 buckets exposed as ctx.storage — uploading, serving via signed URLs, and deleting files from your functions. - [System tables](/docs/concepts/system-tables): Read pending scheduled jobs and stored file metadata through ctx.db.system — a read-only, eventually consistent view outside the mutation snapshot. - [OCC & atomicity](/docs/concepts/occ): Why mutations in one shard are serialized rather than retried, where optimistic-concurrency conflicts still arise, and what atomicity means across shards. - [Sharding](/docs/concepts/sharding): Default __root__ DO, opt-in .shardBy(), and .global() escape hatch. - [Data residency](/docs/concepts/data-residency): Pin Durable Objects to a Cloudflare jurisdiction with .jurisdiction(), and the export→import runbook for moving regions. - [Read replicas & placement](/docs/concepts/read-replicas): Serve one-shot queries from a copy of the shard in the caller's region, pin where a shard is created, and terminate sockets near the client. - [TTL & auto-expiry](/docs/concepts/ttl): Declare a table-level .ttl() so a DO alarm sweep auto-deletes expired rows — sessions, OTPs, and other ephemeral data. - [Migrations](/docs/concepts/migrations): Schema-change SQL for global tables and online, resumable data migrations. - [Backups, export & import](/docs/concepts/backups): Snapshot a deployment, recover a shard to any moment in the last 30 days, and move data in and out as NDJSON. - **Auth & security** - [Adopt in an existing app](/docs/concepts/adopt-in-an-existing-app): Add Lunora to a working product that already has its own auth, Worker, and data layer — without rewriting either. - [Authentication](/docs/concepts/authentication): How ctx.auth threads the signed-in user through queries, mutations, and actions — and feeds row-level security. - [Auth UI](/docs/concepts/auth-ui): Copy-in sign-in, settings, and organization screens for React, Vue, Svelte, Solid, and Angular — the code lands in your project and you own it. - [Row-level security](/docs/concepts/rls): Server-side authorization that decides which rows a procedure can read or write. - [Data masking](/docs/concepts/masking): Column-level redaction on the read path — the companion to row-level security. - [Security](/docs/concepts/security): Lunora's secure-by-default posture — the protections you get for free, how to opt out, and the advisor lints that catch the gaps. - **Frameworks** - [Bring your framework](/docs/frameworks/bring-your-framework): Compose any meta-framework's SSR with Lunora realtime in one Cloudflare Worker. - [React](/docs/frameworks/react): Use Lunora with React — a provider, live useQuery/useMutation hooks, and the SSR-seed → live reactive-loader handoff. - [Next.js](/docs/frameworks/nextjs): Run Lunora alongside Next.js on Cloudflare with the two-worker split — RSC loaders that hydrate into live subscriptions. - [React Native / Expo](/docs/frameworks/react-native): Use Lunora in a React Native / Expo app — the same live hooks, plus an AsyncStorage-backed client and a better-auth Expo bridge. - [Vue](/docs/frameworks/vue): Use Lunora with Vue 3 — a client plugin, live useQuery/useMutation composables, and the SSR-seed → live reactive-loader handoff. - [Solid](/docs/frameworks/solid): Use Lunora with SolidJS — a provider, live createQuery/createMutation primitives, and the SSR-seed → live reactive-loader handoff. - [Svelte](/docs/frameworks/svelte): Use Lunora with Svelte 5 / SvelteKit — context-provided client, live query/mutation stores, and the SSR-seed → live reactive-loader handoff. - [Angular](/docs/frameworks/angular): Use Lunora with Angular — provideLunora in your app config, signal-based liveQuery, imperative mutate, and a connectionStatus signal. - [Astro](/docs/frameworks/astro): Compose Astro's @astrojs/cloudflare worker with Lunora realtime, plus reactive-loader server helpers for .astro frontmatter. - [Nuxt](/docs/frameworks/nuxt): Run Lunora and Nuxt as one Cloudflare Worker — the @lunora/nuxt module mounts /_lunora/** into Nitro, plus reactive-loader server helpers. - [Reactive loaders](/docs/frameworks/reactive-loaders): Your loaders are live — SSR data that hydrates into a real-time subscription with no flash. - [Deploy your framework](/docs/frameworks/deploy): One worker, one deploy — how a composed Lunora + meta-framework app ships to Cloudflare. - [Manual end-to-end verification](/docs/frameworks/verify-live-loaders): How to actually prove live loaders work — scaffold, SSR-curl the preloaded value, two-tab live update. - **Tutorial** - [Build a real-time chat app in 15 minutes](/docs/tutorial/realtime-chat): End-to-end Lunora walkthrough — schema, query, mutation, subscription, React, sharding. - [Tutorial: scaling the chat app](/docs/tutorial/scaling): Take the chat app from one Durable Object to many — shard by channel, put identities in a global table, and keep cross-shard reads off the hot path. - **Migrating** - [Migrating from Convex](/docs/migrating/from-convex): Side-by-side mapping — schema, queries, mutations, actions, React hooks. - [Migrating from a Convex toolkit](/docs/migrating/from-a-convex-toolkit): The second translation step a Drizzle-style schema DSL and a tRPC-style procedure builder add on top of the raw Convex mapping. - [Migrating from Supabase](/docs/migrating/from-supabase): Side-by-side mapping — Postgres tables, RLS, Edge Functions, Auth, Storage, and Realtime. - [Migrating from Firebase](/docs/migrating/from-firebase): Side-by-side mapping — Firestore, Cloud Functions, Auth, Storage, and real-time listeners. - [Upgrading from alpha to 1.0](/docs/migrating/from-alpha): How a 1.0.0-alpha.* app moves to stable — dependency bumps plus every breaking change already landed on the road to 1.0. - **Tooling** - [Generated code](/docs/concepts/generated-code): What @lunora/codegen emits from your schema.ts, and how api / Id / Doc keep server and client in sync. - [TypeScript](/docs/concepts/typescript): Getting the most out of Lunora's end-to-end types — where types come from, what to annotate, and what to let inference do. - [Environment variables](/docs/concepts/environment-variables): Configure secrets and vars — .dev.vars locally, wrangler secrets in production, env bindings inside functions. - [Testing](/docs/concepts/testing): Unit-test queries, mutations, and actions in memory with lunoraTest — no worker, no network. - [Debugging](/docs/concepts/debugging): The tools to reach for when something is broken — doctor, the error overlay, ctx.log, the Studio, insights, and live logs. - [Advisors](/docs/concepts/advisors): Splinter-style lints that catch schema, performance, and security problems — many before you deploy. - [Authoring registry items](/docs/concepts/registry-items): Package a reusable capability — schema, functions, bindings and env vars — as a registry item others install with one command. - [AI coding agents](/docs/concepts/ai-tooling): Teach Claude Code, Cursor, and Copilot how to use Lunora — agent skills, agent-aware dev mode, the docs server, and the MCP server. - [Best practices](/docs/concepts/best-practices): The opinionated idioms that keep a Lunora app fast, safe, and reactive. - **Operations** - [Deployment](/docs/deployment): Wrangler bindings, secrets, and the deploy flow. - [Monorepos and external IaC](/docs/concepts/monorepos-and-iac): Running the Lunora worker as one node in a larger dev graph, deploying it from Terraform/Pulumi/Alchemy, and consuming its generated API from a sibling package. - [Environments & releases](/docs/concepts/environments): Running staging next to production, shipping a preview per pull request, and rolling traffic back when something goes wrong. - [Production checklist](/docs/production-checklist): Everything to verify before a Lunora app takes real traffic — bindings, secrets, admin tokens, rate limits, RLS, migrations, observability. - [Observability](/docs/concepts/observability): Ship Lunora's logs, traces, and metrics to any OTLP collector — the otlpSink worker option, ctx.log/ctx.trace/ctx.metrics, the zero-config container exporter, and the one wire contract they share. - [Architecture](/docs/architecture): The full picture — topology, request lifecycle, the data tiers, the consistency model, and the design decisions behind them. - [Design boundaries](/docs/non-goals): The things Lunora deliberately does not do — each with the reason it's a boundary and the escape hatch when you need past it. - [Limits](/docs/limits): Cloudflare ceilings you should keep in your head. - [Versioning & stability](/docs/versioning): What SemVer means for Lunora packages — release channels, stability tiers, and the experimental surface. - **Lunora Cloud** - [Monitoring](/docs/cloud/monitoring): The Lunora cloud is a managed OpenTelemetry backend + control plane — deploy to it and your traces, logs, metrics, and AI generations flow in automatically, with a Traces waterfall, Issues, and Logs to read them. - **Reference** - [Errors & warnings reference](/docs/errors): Every well-known Lunora error code — its HTTP status, what it means, and what to do about it. - [Wire protocol](/docs/concepts/wire-protocol): The language-independent Lunora client↔server wire protocol and the golden fixtures every SDK is tested against. - [Non-JS SDKs](/docs/concepts/non-js-sdks): Generate a typed, self-contained Lunora client for Python, Go, Ruby, Rust, Swift, Java, Kotlin or Dart/Flutter — vendored into your project and pinned to your CLI version. - Packages - [Package Directory](/docs/packages): Browse the Lunora package ecosystem — the server runtime, validators, client SDK, framework adapters, and opt-in add-ons, organized by category. - **Core Runtime** - lunora - [lunora](/docs/packages/lunorash): The Lunora umbrella package — one install for the server authoring API, worker runtime, Durable Objects, and the lunora CLI, exposed through lunorash/* subpaths. - Server - [@lunora/server](/docs/packages/server): Authoring API — defineSchema, query, mutation, action, validators. - Values - [@lunora/values](/docs/packages/values): The validator runtime — v.*, Validator, Infer, Id, ValidationError, and JSON Schema export. - Runtime - [@lunora/runtime](/docs/packages/runtime): The Worker entrypoint — createWorker, RPC envelope, shard routing. - Do - [@lunora/do](/docs/packages/do): The Durable Object base classes — ShardDO and SessionDO. - D1 - [@lunora/d1](/docs/packages/d1): D1 Sessions API client + migration runner for global tables. - Errors - [@lunora/errors](/docs/packages/errors): The unified error layer — LunoraError, the error catalog, isLunoraError, invariant/unreachable, and the CLI renderer. - Fingerprint - [@lunora/fingerprint](/docs/packages/fingerprint): Zero-dependency error fingerprinting — one stable grouping hash that collapses noisy errors into Issues for Studio and the Cloud. - Sql Store - [@lunora/sql-store](/docs/packages/sql-store): Internal dialect-parameterized SQL store core behind the .global() table backends — depend on @lunora/d1 or @lunora/hyperdrive, not this. - **Platform Hosts** - Platform - [@lunora/platform](/docs/packages/platform): The host contracts every Lunora target implements — ShardHost, SocketHost, ShardDirectory, ShardKvStore, SchedulerHost — plus the capability matrix codegen reads. - Platform Cloudflare - [@lunora/platform-cloudflare](/docs/packages/platform-cloudflare): The Cloudflare implementation of the @lunora/platform host contracts. - Shard Engine - [@lunora/shard-engine](/docs/packages/shard-engine): The host-neutral reactive engine — everything a shard does that isn't provider-specific. - Platform Node - [@lunora/platform-node](/docs/packages/platform-node): The Node host for the @lunora/platform contracts — experimental, no lunora dev --target node yet, and no SemVer promise until it graduates. - **Observability** - Observability - [@lunora/observability](/docs/packages/observability): Host-neutral telemetry — logs, metrics, traces, request logs, and issue grouping. - **Client & UI** - Client - [@lunora/client](/docs/packages/client): Framework-agnostic browser/edge client. - React - [@lunora/react](/docs/packages/react): React 18+/19 hooks built on @lunora/client, with React Server Component data loading. - React Native - [@lunora/react-native](/docs/packages/react-native): React Native / Expo bindings for Lunora — the @lunora/react hooks plus an AsyncStorage-backed client factory and a better-auth Expo bridge. - Vue - [@lunora/vue](/docs/packages/vue): Vue 3 composables built on @lunora/client — live queries, optimistic mutations, and an SSR hydration handoff. - Solid - [@lunora/solid](/docs/packages/solid): SolidJS bindings built on @lunora/client — live query signals, optimistic mutations, and an SSR hydration handoff. - Svelte - [@lunora/svelte](/docs/packages/svelte): Svelte 5 bindings built on @lunora/client — live query stores, optimistic mutations, and an SSR hydration handoff. - Angular - [@lunora/angular](/docs/packages/angular): Angular reactive adapter for Lunora — signal-based live queries and mutations. - Nuxt - [@lunora/nuxt](/docs/packages/nuxt): Nuxt module: single-worker composition (mounts /_lunora/* into Nitro) plus reactive-loader server helpers. - Db - [@lunora/db](/docs/packages/db): Optimistic, offline-first client data layer on TanStack DB. - Studio - [@lunora/studio](/docs/packages/studio): The Lunora Studio — a local admin console for your schema, data, functions, logs, and advisors. - Astro - [@lunora/astro](/docs/packages/astro): Astro integration: single-worker composition plus reactive-loader server helpers. - **Build & Tooling** - Vite - [@lunora/vite](/docs/packages/vite): The recommended dev-time experience — codegen, HMR, overlay. - **Codegen** - Codegen - [@lunora/codegen](/docs/packages/codegen): Emits _generated/{api,server,dataModel}.ts from your schema.ts. - **CLI** - Cli - [@lunora/cli](/docs/packages/cli): The standalone `lunora` binary — scaffold, codegen, deploy. - **Dev Tools** - Config - [@lunora/config](/docs/packages/config): Internal shared CLI + Vite config layer: wrangler.jsonc validation, binding inference, and .dev.vars scaffolding. - Testing - [@lunora/testing](/docs/packages/testing): In-memory harness for queries, mutations, and actions, plus E2E mail-catcher helpers. - **Advisor** - Advisor - [@lunora/advisor](/docs/packages/advisor): Schema and query lints — splinter-style advisors that surface in the Studio Advisors view, most of them at codegen time before you ship. - **Add-ons** - @lunora/auth - [@lunora/auth](/docs/packages/auth): A thin better-auth wrapper for Lunora — email/password, OAuth, plugins, D1-backed. - [@lunora/auth plugins](/docs/packages/auth/plugins): Org, admin, and other better-auth plugins surfaced as first-class Lunora middleware. - Mail - [@lunora/mail](/docs/packages/mail): Transactional email for Lunora — Cloudflare Email Workers or Resend, React templates, queue-backed sends. - Storage - [@lunora/storage](/docs/packages/storage): R2-backed object storage with worker-signed and S3 presigned URLs. - Scheduler - [@lunora/scheduler](/docs/packages/scheduler): Durable Object-backed scheduling for Lunora — runAfter/runAt, code-first cron jobs, and bounded-concurrency workpools. - Queue - [@lunora/queue](/docs/packages/queue): Cloudflare Queues for Lunora — defineQueue producers, a generated queue() push consumer (or HTTP pull), and the typed ctx.queues surface. - Container - [@lunora/container](/docs/packages/container): Deploy Docker containers alongside your Lunora app, called from actions over ctx.containers. - Agent - [@lunora/agent](/docs/packages/agent): Durable AI agents — defineAgent compiles a replay-safe tool-loop onto Cloudflare Workflows with live thread subscriptions. - Ai - [@lunora/ai](/docs/packages/ai): Workers AI inference from your functions, provider-agnostic, Workers AI by default. - Bindings - [@lunora/bindings](/docs/packages/bindings): The lightweight Cloudflare binding helpers for Lunora in one install — ctx.kv, ctx.images, ctx.analytics, ctx.pipelines, ctx.vectors, ctx.r2sql — with per-binding subpaths and tree-shaking. - Browser - [@lunora/browser](/docs/packages/browser): Cloudflare Browser Rendering for Lunora — ctx.browser (action-only) for headless screenshots, PDFs, HTML scraping, and arbitrary page evaluation. - Cloudflare Access - [@lunora/cloudflare-access](/docs/packages/cloudflare-access): Cloudflare Access (Zero Trust) identity for Lunora — feed the verified Access identity into ctx.auth and RLS via a resolveIdentity adapter, from a Worker-scoped Access policy or a hostname-scoped application's Cf-Access-Jwt-Assertion JWT. - Flags - [@lunora/flags](/docs/packages/flags): OpenFeature-based feature flags for Lunora — ctx.flags, useFlag, and a first-class Cloudflare Flagship provider with any OpenFeature provider pluggable. - Hyperdrive - [@lunora/hyperdrive](/docs/packages/hyperdrive): Bring-your-own Postgres/MySQL via Cloudflare Hyperdrive — an action-only ctx.sql, or a reactive .global() backend. - Mcp - [@lunora/mcp](/docs/packages/mcp): Model Context Protocol servers for Lunora — one exposing a deployment to AI agents, one exposing the framework's documentation. - Notify - [@lunora/notify](/docs/packages/notify): Multi-channel notifications — ctx.notify / ctx.push over @visulima/notification, with edge-safe Web Push and FCM. - @lunora/payment - [@lunora/payment](/docs/packages/payment): Provider-agnostic payments for Lunora — Stripe/Polar/Autumn/Dodo/Creem adapters, webhook sync, and a payment/subscription state machine. - [@lunora/payment — Stripe](/docs/packages/payment/stripe): End-to-end tutorial for wiring the Stripe adapter into ctx.payments — checkout, subscriptions, entitlements, metered usage, refunds, and verified webhooks. - [@lunora/payment — Polar](/docs/packages/payment/polar): Merchant-of-Record payments on Lunora with Polar — checkout, subscriptions, entitlements, usage metering, and Standard-Webhooks sync. - [@lunora/payment — Autumn](/docs/packages/payment/autumn): End-to-end tutorial for wiring the Autumn adapter into ctx.payments — attach a product, check/track features Autumn owns, verify Svix webhooks, and reconcile. - [@lunora/payment — Dodo Payments](/docs/packages/payment/dodopayments): Merchant-of-Record payments on Lunora with Dodo Payments — checkout, subscriptions, first-class refunds, usage metering, and Standard-Webhooks sync. - [@lunora/payment — Creem](/docs/packages/payment/creem): Accept payments and subscriptions through Creem — an EU-friendly, product-based Merchant-of-Record — with hosted checkout, a billing portal, and verified webhooks synced through Lunora's payment state machine. - Ratelimit - [@lunora/ratelimit](/docs/packages/ratelimit): Token-bucket, fixed-window, and sliding-window rate limiting as procedure middleware. - Replica - [@lunora/replica](/docs/packages/replica): Local-first replica runtime for Lunora — EventEmitter, subscriptions, snapshot DO, and replay. - [@lunora/replica — Getting started](/docs/packages/replica/getting-started): Build an offline-capable todo app with the local SQLite mirror and EventsSync. - Guides - [Custom SQLite adapters](/docs/packages/replica/guides/custom-adapter): Implement SqliteAdapter for any SQLite runtime (React Native, bun:sqlite, expo-sqlite, etc.). - Seed - [@lunora/seed](/docs/packages/seed): Deterministic, schema-driven seeding: realistic fake data generated from defineSchema. - Workflow - [@lunora/workflow](/docs/packages/workflow): Durable, multi-step execution that replays deterministically — built on Cloudflare Workflows. - **Web3** - X402 - [@lunora/x402](/docs/packages/x402): Agentic payments over the x402 protocol — charge agents per request (charge rail) and let your agents pay 402-gated resources (pay rail).