Skip to content
DocsconceptsDocumentation

Environment variables

Configure secrets and vars — .dev.vars locally, wrangler secrets in production, env bindings inside functions.

Last updated:

A Lunora app reads its configuration (API keys, signing secrets, allowlists) from the Cloudflare Worker's env. There are two kinds of value:

KindWhere it livesVisible in the dashboardUse for
varvars block in wrangler.jsoncyes (plain text)non-secret config, feature flags
secretwrangler secret put (encrypted, write-only)noAPI keys, signing secrets

Both surface the same way at runtime, as properties on env. The only difference is how you set them and whether the value is encrypted at rest. Use a secret for anything sensitive; use a var for non-secret config you're happy to see in plain text.

Locally: .dev.vars

Local secrets and vars live in .dev.vars (a dotenv-style file), which wrangler dev and the Vite dev server load automatically. .dev.vars is gitignored, so never commit it. Instead commit a .dev.vars.example listing the keys your worker needs, with placeholder values:

# .dev.vars.example
AUTH_SECRET="replace-with-openssl-rand-hex-32"
AUTH_URL="http://localhost:5173"
STORAGE_SECRET="replace-with-openssl-rand-hex-32"

Auto-scaffolding

When you run lunora dev (or start Vite) without a .dev.vars, @lunora/config offers to generate one from the example: placeholders for keys Lunora can generate, such as AUTH_SECRET, LUNORA_ADMIN_TOKEN, and STORAGE_SIGNING_SECRET, are filled with fresh random values. Provider-issued keys, such as OPENAI_API_KEY or GITHUB_CLIENT_SECRET, stay as placeholders for you to fill in, and everything else is copied verbatim. If .dev.vars exists but is missing keys the example lists (say, you recently enabled an addon), it offers to append just those. Non-interactive runs (CI) skip the prompt.

You can also manage keys by hand:

lunora env set RESEND_API_KEY "re_..."   # write a single key
lunora env list                          # show configured keys
lunora env doctor                        # check .dev.vars against its example

lunora env doctor reports missing keys, still-unset placeholders, and stray extras, and exits non-zero when anything is actionable, so it works as a CI gate or a pre-dev sanity check.

Which file wins

The dev worker gets its env the way wrangler dev builds it, and Lunora's dev checks read it the same way:

  1. The vars in wrangler.jsonc. With CLOUDFLARE_ENV set, only that env.<name> block's own vars, because vars is not inherited.
  2. .dev.vars.<env> (with CLOUDFLARE_ENV), else .dev.vars. Values here override a var of the same name.
  3. Only when there is no .dev.vars: .env, .env.local, then .env.<env> and .env.<env>.local. Later files win and ${OTHER} references expand. CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV=false skips these files. The shell environment joins them only with CLOUDFLARE_INCLUDE_PROCESS_ENV=true, or when wrangler.jsonc declares a secrets block.
  4. With a secrets block, the worker keeps only the keys that are a var or listed in secrets.required.

Your shell environment never reaches the worker otherwise. Exporting a key in the terminal that runs lunora dev does not set it for the worker.

Checking lunora/env.ts at dev start

If the app declares a defineEnv contract in lunora/env.ts, lunora dev and the Vite plugin check every key in it against that env when the dev server starts. defineEnv normally validates a key on its first read, so a missing key would otherwise show up as a 500 from whichever request reads it first. The check prints a warning instead and never stops the server.

With the Vite plugin, the check runs again each time you save or delete env.ts. A .dev.vars, .env or wrangler.jsonc edit restarts the Vite dev server, and the restart runs the check too. Without Vite, lunora dev checks once at startup. Wrangler reloads the worker on those edits without running the check again, so restart lunora dev to see an updated result.

On SvelteKit and Nuxt the check reads wrangler.dev.jsonc, the config the dev worker runs. A binding the dev session leaves out because you are not logged in to Cloudflare (Workers AI, Artifacts) counts as missing.

env.ts runs in Node, through jiti, on every check, and so do the modules it imports. Keep it to defineEnv and the validators. A module the Workers runtime provides (a cloudflare: import) or a tsconfig path alias jiti cannot resolve makes the check report that it could not run. Keys are then validated on first read, as before.

In production: secrets and vars

Set secrets with wrangler secret put (you'll be prompted for the value; it's encrypted and never echoed back):

wrangler secret put AUTH_SECRET
wrangler secret put RESEND_API_KEY
wrangler secret put STORAGE_SECRET

Or push everything from your local .dev.vars at once:

lunora env push --yes

Set non-secret vars declaratively in wrangler.jsonc; they ship with the Worker and are visible in the dashboard:

{
    // ...
    "vars": {
        "AUTH_URL": "https://app.example.com",
        "LOG_LEVEL": "info",
    },
}

The security layer reads its CORS allowlist from config this way, without a code change: set LUNORA_ALLOWED_ORIGINS as a var and the worker picks it up at request time (see Security).

Lunora never logs secret values. The lunora/env.ts check above covers only the local dev env. A forgotten wrangler secret put is caught by the remote-secret gate in lunora deploy, and it is best-effort: it skips a first deploy, or a wrangler that is not logged in, because it cannot query either. Run lunora env diff --env <name> against the target to compare local and deployed secret names before shipping.

Accessing env inside your app

Cloudflare hands the Worker its bindings as the env object. In Lunora you wire configuration from env at the worker entry (into createWorker, the generated DO factory thunks, and adapter setup) rather than reading globals inside handlers:

// src/server/index.ts
import { createAuth } from "@lunora/auth";

const auth = createAuth({
    secret: env.AUTH_SECRET, // a secret from `wrangler secret put`
    baseURL: env.AUTH_URL, // a var from wrangler.jsonc
    socialProviders: { github: { clientId: env.GH_CLIENT_ID, clientSecret: env.GH_CLIENT_SECRET } },
});

The same env flows into the binding thunks the generated factories accept, for example a Vectorize binding (env) => ({ "docs-body": env.DOCS_BODY }) or a KV namespace createKv({ namespace: env.KV }). This keeps every secret read in one place (the entry), so a handler never reaches for a global and your functions stay testable against the in-memory harness.

Adapters built on this env plumbing then expose the live capability on the function ctx (ctx.vectors, ctx.ai, ctx.storage, and so on), so your queries/mutations/actions consume configured services without touching raw bindings themselves.

The rule: never commit secrets

  • .dev.vars is gitignored. Commit .dev.vars.example (placeholders only).
  • Production secrets go through wrangler secret put (encrypted), not into wrangler.jsonc's vars (plain text, committed).
  • Run lunora env doctor in CI to catch a checked-in placeholder or a missing key before it ships.