Skip to content
Lunora
DocsDocumentation

Getting started

Scaffold a Lunora app and run the dev loop in under a minute.

Getting started

Last updated:

The fastest way to start a Lunora project is the official template. It wires up Vite, the codegen plugin, a starter schema, and a working Worker entrypoint, all pointing at a wrangler.jsonc you can deploy straight to your own account.

Lunora is in alpha. Install from the @alpha dist-tag (the commands below already do) and expect breaking changes until the first stable release. The npm package is lunorash (the unscoped lunora name is taken on npm), but the CLI binary it installs is still lunora.

Note npm view <pkg> version reports 0.0.0 for every @lunora/* package: that is the placeholder on latest. The real version lives on the alpha dist-tag (npm view <pkg> dist-tags). Reading latest makes a released package look unpublished.

Using pnpm's minimumReleaseAge? The packages release independently and often, so a maturation window will hold back some of them and leave you with a set that no longer resolves together:

ERR_PNPM_NO_MATURE_MATCHING_VERSION  Version 1.0.0-alpha.39 (released 2 hours ago)
of @lunora/seed does not meet the minimumReleaseAge constraint

Exclude the scope rather than turning the window off everywhere:

# pnpm-workspace.yaml
minimumReleaseAge: 1440
minimumReleaseAgeExclude:
    - "@lunora/*"
    - lunorash

Requirements

  • Node ^22.15.0 || >=24.11.0: the range every published Lunora package declares in engines.
  • A package manager: pnpm >=10.32.1, or npm, yarn, or bun. The scaffolded app pins none of them; the tabs below cover all four.
  • A Cloudflare account, only needed to keep a deployment. Local dev needs none, and lunora deploy --temporary publishes a live URL without one (the Free plan works once you're ready to claim it).

Scaffold

Create a project from the official template:

pnpm dlx lunorash@alpha init my-app

Then install and start the dev loop:

cd my-app
pnpm install
pnpm dev

The CLI lays down the standard layout:

my-app/
├── lunora/
│   ├── schema.ts          # defineSchema / defineTable
│   ├── messages.ts        # query / mutation / action
│   └── _generated/        # codegen output (don't edit)
├── src/
│   ├── server/index.ts    # createWorker + ShardDO subclass
│   └── client/main.tsx    # LunoraProvider + your React app
├── wrangler.jsonc         # DO + D1 + R2 bindings
└── vite.config.ts         # lunora() Vite plugin

Run

pnpm dev boots Vite and Wrangler in one terminal. Edits to lunora/schema.ts trigger codegen and a typed-API hot reload within ~200 ms.

Throw inside a handler and the @visulima/vite-overlay integration shows a mapped source frame pointing at your code, not the bundle.

Deploy

pnpm lunora deploy

This calls wrangler deploy, runs pending D1 migrations, and publishes the Worker. Everything lives on your account, reachable through your own *.workers.dev hostname or a custom domain.

No account yet? pnpm lunora deploy --temporary deploys to a Wrangler-provisioned short-lived account: your Worker is live for ~60 minutes, then you claim it to make it permanent or it's deleted.

Edit on GitHub

On this page

RequirementsScaffoldRunDeploy

Related topics

06 topics