Skip to content
DocspackagesDocumentation

@lunora/codegen

Emits _generated/{api,server,dataModel}.ts from your schema.ts.

PackagesCodegen

@lunora/codegen reads your backend and writes the types that make it type-safe end to end. It parses lunora/schema.ts plus every function file under lunora/, then writes lunora/_generated/ so the rest of your app gets typed access to its own queries, mutations, actions, and tables.

You rarely call this package directly. The @lunora/vite plugin runs it on every schema change, and the lunora codegen command runs it once on demand. Both share this same core, so the output is consistent when they use the same options.

What it generates

The core outputs, always written:

  • api.ts: the typed api.<file>.<function> (and internal.*) function references your client and server code call through.
  • server.ts: the query / mutation / action / internalQuery / internalMutation / internalAction / definePolicy procedure builders, bound to your schema.
  • dataModel.ts: the Doc<"messages"> / Id<"users"> types derived from your tables.

It also emits app.ts, functions.ts, shard.ts, and the Drizzle schemas below, plus crons.ts, containers.ts, workflows.ts, vectors.ts, seed.ts, and the OpenAPI / OpenRPC spec files, each only when you use the matching feature.

The Drizzle schemas

drizzle.shard.ts and drizzle.global.ts mirror your tables as Drizzle sqliteTable definitions, split by where the rows live: .global() tables (D1) go in drizzle.global.ts, everything else (the default root shard and .shardBy() tables) in drizzle.shard.ts. A project with no table on one side gets an empty module, not a missing file.

They exist for the escape hatch: ctx.db covers the typed path, and when you need raw Drizzle — a @lunora/d1 client.drizzle query against your global tables, a hand-written join, a Drizzle Studio config — you import the table objects instead of redeclaring them.

import { drizzle } from "drizzle-orm/d1";
import { eq } from "drizzle-orm";

import { users } from "./lunora/_generated/drizzle.global.js";

const rows = await drizzle(env.DB).select().from(users).where(eq(users.email, email));

searchIndexes are not emitted — Drizzle has no sqliteTable abstraction for SQLite full-text search (FTS5) virtual tables, and the runtime handles that plumbing outside Drizzle. Nothing you write has to import these files; ignore them if you never reach for Drizzle directly.

When it runs

// vite.config.ts — codegen runs on startup and on every schema change
import { lunora } from "@lunora/vite";

export default defineConfig({ plugins: [lunora()] });

Under lunora dev, codegen runs in watch mode: save a function or change the schema and the regenerated types are in the module graph before you switch windows.

To use the lazy registry for good, set it in lunora.config.ts:

export default { codegen: { lazyFunctions: true } } satisfies LunoraConfig;

Codegen reads the key itself, so every entry point that writes or checks _generated/ agrees: CLI codegen, dev, prepare, build, deploy and verify, dev watch runs, Studio edits, and the Vite and Rspack plugins. Write it as a boolean literal; a computed value logs a warning and stays eager.

For a single run, pass --lazy-functions or set LUNORA_LAZY_FUNCTIONS to 1 or true in the shell. Any one opt-in enables lazy imports; a false flag value does not override the config or an enabled environment setting. With none enabled, generation stays eager. Lazy imports are the fix for a large app that fails to deploy with error 10021; see Worker startup CPU limit for when to use them and what they cost. deploy --prebuilt keeps the output from an earlier build without regenerating.

Don't edit _generated/

These files are derived from your schema and overwritten on every run, so any hand edit is lost the next time codegen runs. Change schema.ts or your function files instead, then let codegen catch up.

Commit lunora/_generated/. The output is deterministic, so a stale committed copy is a real diff — but no command checks that for you: lunora verify runs codegen as a dry run (writing nothing) and lunora prepare silently overwrites the files. The schema-drift gate both run measures a different artifact, the committed .lunora-schema.json baseline. To gate the generated types in CI, regenerate and diff:

lunora codegen
git diff --exit-code lunora/_generated

The .js extension exception

The emitted modules are consumed under NodeNext, where relative imports need a file extension. So codegen deliberately writes .js into the imports it generates:

import { api } from "./_generated/api.js";

This is the one place in a Lunora project where hand-written .js extensions are correct. Your own lunora/ source still omits extensions like the rest of the codebase.

Calling it programmatically

If you need codegen in your own tooling, runCodegen takes a single options object and returns the result, including any static schema advisories found this run:

import { formatAdvisories, runCodegen } from "@lunora/codegen";

const result = runCodegen({ projectRoot: process.cwd() });

console.log(`wrote _generated/ -> ${result.outputDirectory}`);

if (result.advisories.length > 0) {
    console.warn(formatAdvisories(result.advisories));
}

Common options:

  • projectRoot (required): the directory containing the lunora/ folder.
  • dryRun: run discovery and emit (so parse errors still surface) without writing files. outputDirectory is still the path that would have been written.
  • lint: run the static schema advisor (default true); when false, result.advisories is empty. To keep the advisor but drop its lower levels, set advisor.minSeverity in lunora.config.ts instead (see below).
  • apiSpec: "openapi" (default), "openrpc", "both", or "none".
  • lazyFunctions: set to true to emit per-module lazy imports. Omitted or false keeps the eager registry unless codegen.lazyFunctions in lunora.config.ts enables it.
  • lunoraDirectory: override the lunora subdirectory name.
  • target: the deploy target that tailors the emitted ctx.* surface. Default: the target string in lunora.config.ts, then "cloudflare". The registered targets are "cloudflare", "node" and "celld"; each gates the surface by its capability matrix from @lunora/platform. Any other name emits the full Cloudflare surface un-gated and a platform_unknown_target diagnostic.

API reference

CodegenResult

Type: interface. The value runCodegen returns. Its generated field holds the generated file contents, keyed by name. advisories holds the static advisor findings, and cronTriggers lists the Cron trigger expressions.

lintSchema(options)

Type: (options: LintSchemaOptions) => Finding[]. Runs the static schema advisor and returns its findings. Use it when you need the advisories without a full codegen run. Surfacing them (console, error overlay, Studio) is up to the caller.

generateSdk(document, target)

Type: (document: OpenRpcDocument, target: SdkTarget) => Promise<SdkResult>. Generates a client SDK in the target's language from an OpenRPC document. Import it from @lunora/codegen/sdk. The lunora sdk generate command calls it. See the lunora sdk section for the command.

Trimming advisories (advisor.minSeverity)

Codegen writes every static advisory into _generated/shard.ts, where the studio's Advisors table reads it, and returns the same list in result.advisories. Several INFO rules fire once per procedure, so in a growing project most of those advisories are INFO. Set a floor in lunora.config.ts to leave them out:

// lunora.config.ts
import type { LunoraConfig } from "./lunora/_generated/app";

export default {
    advisor: { minSeverity: "warn" },
} satisfies LunoraConfig;

minSeverity is "info" (the default, everything), "warn" or "error". Findings below it are dropped from result.advisories, and so from the terminal and the dev overlay, and from the generated shard. It changes emission and display only. An ERROR is at or above every floor, so the gate that fails lunora codegen, lunora deploy and vite build on ERROR-level advisories cannot be turned off this way. lint: false is still the only way to skip the advisor entirely.

Write it as a string literal, like target: codegen reads it by parsing the file. An unknown level or a computed value filters nothing and adds one advisor_min_severity_invalid WARN saying why.