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:
| Kind | Where it lives | Visible in the dashboard | Use for |
|---|---|---|---|
| var | vars block in wrangler.jsonc | yes (plain text) | non-secret config, feature flags |
| secret | wrangler secret put (encrypted, write-only) | no | API 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 examplelunora 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:
- The
varsinwrangler.jsonc. WithCLOUDFLARE_ENVset, only thatenv.<name>block's ownvars, becausevarsis not inherited. .dev.vars.<env>(withCLOUDFLARE_ENV), else.dev.vars. Values here override avarof the same name.- 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=falseskips these files. The shell environment joins them only withCLOUDFLARE_INCLUDE_PROCESS_ENV=true, or whenwrangler.jsoncdeclares asecretsblock. - With a
secretsblock, the worker keeps only the keys that are avaror listed insecrets.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_SECRETOr push everything from your local .dev.vars at once:
lunora env push --yesSet 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.varsis gitignored. Commit.dev.vars.example(placeholders only).- Production secrets go through
wrangler secret put(encrypted), not intowrangler.jsonc'svars(plain text, committed). - Run
lunora env doctorin CI to catch a checked-in placeholder or a missing key before it ships.