Environment Variables Reference
Every environment variable the kit declares, how to set them locally and in deployed environments, and how to add your own.
All configuration that differs between environments is an environment variable, declared once and validated by Void. This page lists every variable the kit declares.
This page is part of the Configuration documentation.
Quick Start
pnpm kit:setup # .env from env.example, database, migrations, the apppnpm --filter web exec void env check # ✓ Local .env values are valid.pnpm kit:setup creates apps/web/.env from env.example and writes a random BETTER_AUTH_SECRET of its own; on an existing .env it only adds the keys it lacks and never changes a value (except a missing or example secret). Only these variables are required. Everything else has a default; env.example has working dev values for all of them except the secret.
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54323/postgresSITE_URL=http://localhost:5173PRODUCT_NAME=MakerkitBETTER_AUTH_SECRET=<32+ random characters: pnpm kit:setup writes one>The app refuses env.example's old public secret (dev-only-secret-change-me-…) everywhere: void secret put won't upload it and a deployed Worker holding it fails to start, so Void's readiness check rolls the deploy back. A deployed app whose SITE_URL still points at localhost fails every request with the command that fixes it.
How Void Handles Env
- One schema.
apps/web/env.tscallsdefineEnvwith the kit's keys (apps/web/config/kit-env.ts) plus yours. Read values withenvfromvoid/env, inside functions, never at module top level. - All keys are server values. The kit has no
VITE_*variables. The browser receives the public subset at request time throughuseShared().config, so a change needs no rebuild. - One local file. Void reads only
apps/web/.env. It refuses to start while any other.env.*file (such as.env.localor.env.example) exists inapps/web, which is why the template is calledenv.example. - Fail fast. Values are checked by
void env check, byvoid secret putand when the Worker starts. An invalid or missing required value stops the app, and the diagnostic names the key with the value redacted.
Deployed Environments
Every key is a Worker secret; plaintext vars are not used.
cd apps/webpnpm exec void secret put PRODUCT_NAME # prompts for the valuepnpm exec void secret sync production-secrets.txt # bulk, dotenv formatpnpm exec void secret list # names only, never valuespnpm exec void env check --remote # required keys present remotely?void deployrefuses to deploy when a required key (SITE_URL,PRODUCT_NAME,BETTER_AUTH_SECRET) is missing remotely. Keys with a default can be left unset.DATABASE_URLis never a Worker secret: deployed Workers connect through theHYPERDRIVEbinding. Export it in the shell that runsvoid deploy(in Workers Builds, a build secret), which uses it to create the Hyperdrive config and run migrations. A Worker that already has aDATABASE_URLsecret keeps bypassing Hyperdrive until you runvoid secret delete DATABASE_URL.- On direct Cloudflare deploys, secret commands target the Worker named in
void.lock.json(resolved.name): production, the kit's one deployed environment (Deployment). void deploynever uploads.env. Keep local credentials out of production secrets files.
Reference
Core
| Variable | Default | Allowed values | Effect |
|---|---|---|---|
DATABASE_URL | unset | Postgres connection URL | Local dev and deploy-time migrations only. Locally, PGlite from pnpm db:start. Never set it as a Worker secret: it would bypass Hyperdrive, which deployed Workers use. |
SITE_URL | required | URL; https unless localhost/127.0.0.1 | Canonical URL for links built without a request (emails, jobs). |
PRODUCT_NAME | required | string | Product name in metadata, UI and emails. |
BETTER_AUTH_SECRET | required | string, 32+ characters | Signs sessions and auth tokens. Generate one per environment (openssl rand -base64 32); changing it signs everyone out and invalidates pending email links. |
APP_HOME_PATH | /dashboard | path starting with / | Where signed-in users land (after sign-in, and when they open a page for signed-out visitors); first navigation item. Put its page in apps/web/pages/(app)/ so it needs a session. |
DEFAULT_THEME_MODE | light | light, dark, system | Theme for visitors without a theme cookie (or for everyone when the toggle is off). |
Account Mode
| Variable | Default | Allowed values | Effect |
|---|---|---|---|
ACCOUNT_MODE | hybrid | personal-only, organizations-only, hybrid | Personal accounts, organizations, or both. Derives most feature flags; see Account Modes. |
ENABLE_PERSONAL_ACCOUNT_BILLING | false | boolean | Lets personal accounts subscribe (ignored in organizations-only). Turned off while Stripe stays on, a user with an open subscription keeps /settings/billing read-only, with no nav entry: link to it yourself. |
STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET | unset | string | Stripe billing, on when both are set and off when neither is. Worker secrets. If only one is set, every page and API request answers 500, and the logs name the missing key. Void checks each key on its own, so this pairing isn't caught at deploy time. |
Plan price ids (your keys, e.g. STRIPE_PRICE_PRO_MONTHLY) | unset | string | Declared by you in apps/web/env.ts and named by each plan's priceEnv in config/billing.config.ts. Required while billing is on: a missing or blank one stops the app with the plan's name and the key. Unset is fine while billing is off. |
MAX_ORGANIZATIONS_PER_USER | 5 | whole number, 0–100 | How many organizations one user may own; creating another answers 403 ORGANIZATION_LIMIT_REACHED. 0 removes the limit. Anything else (-1, 2.5) fails at boot. |
INVITATION_EXPIRES_IN_DAYS | 7 | whole number, 1–30 | How many days an invitation's link works. |
MAX_PENDING_INVITATIONS | 50 | whole number, 1–1000 | Pending (unexpired) invitations one organization may hold; inviting past it answers 409 INVITATION_LIMIT_REACHED. |
Invitation send limits aren't env vars: they live in apps/web/config/invitations.config.ts, the one place to change them. invitesPerHour (default 20) caps the invitations one user creates per hour, counted in the database across all their organizations, including an expired invitation's replacement; past it the invite answers 429 INVITE_RATE_LIMITED with the wait. resendCooldownMinutes (default 5) is how long before the same invitation can be resent (429 RESEND_TOO_SOON). Page actions skip Better Auth's HTTP rate limits: together with MAX_PENDING_INVITATIONS, these are the limits on invitation emails. The hourly count is re-checked after each insert, so a burst of parallel invites can't pass it.
Authentication
| Variable | Default | Allowed values | Effect |
|---|---|---|---|
AUTH_PASSWORD | true | boolean | Email and password sign-in. Off: refused by the server too, not only hidden. |
AUTH_MAGIC_LINK | false | boolean | Email magic-link sign-in. Off: the Better Auth plugin isn't registered. See Authentication. |
AUTH_EMAIL_OTP | false | boolean | Sign-in with an emailed 6-digit code. Off: the Better Auth plugin isn't registered. See Authentication. |
AUTH_PASSKEY | false | boolean | Passkey sign-in, passkeys added at /settings/security. Its table always exists, so switching it needs no migration. See Passkeys. |
AUTH_TWO_FACTOR | false | boolean | Two-factor authentication (authenticator app and backup codes) on every sign-in method, set up at /settings/security. Its tables always exist, so switching it needs no migration. See Two-Factor Authentication. |
AUTH_GOOGLE_CLIENT_ID, AUTH_GOOGLE_CLIENT_SECRET | unset | string | Google sign-in, on when both are set. One alone makes every request answer 500, naming the missing key in the logs. Other providers follow the same AUTH_<PROVIDER>_CLIENT_ID / _SECRET convention with an entry in auth.config.server.ts. See OAuth Sign-In. |
DISPLAY_TERMS_AND_CONDITIONS_CHECKBOX | false | boolean | Shows a terms checkbox on sign-up. |
TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY | unset | string | Cloudflare Turnstile on sign-up, sign-in, reset and emailed links and codes, on when both are set (one alone makes every request answer 500, naming the missing key in the logs). The site key is public; the secret is a Worker secret. See Bot Protection. |
AUTH_RATE_LIMIT | true | boolean | Better Auth's per-IP rate limits, stored in the database and keyed on Cloudflare's client IP (cf-connecting-ip). Sign-in: 5 a minute; sign-up: 3 a minute; reset request and verification resend: 3 per 5 minutes; anything else under /api/auth: 100 a minute. A blocked form shows "Too many attempts". The limits are AUTH_RATE_LIMIT_RULES in packages/better-auth/src/rate-limit.ts; change one in apps/web/config/auth.config.server.ts → rateLimitRules (merged path by path), not in the package. Keep it on when deployed; e2e needs it on (each test sends its own IP). Locally every request shares one IP, so set false in apps/web/.env if quick retries get in your way. |
PASSWORD_REQUIRE_SPECIAL_CHARS | false | boolean | Password must contain a character that isn't a letter or digit. |
PASSWORD_REQUIRE_NUMBERS | false | boolean | Password must contain a number. |
PASSWORD_REQUIRE_UPPERCASE | false | boolean | Password must contain an uppercase letter. |
Booleans accept true, false, 1 or 0 (any case). Passwords are always 8–128 characters. The PASSWORD_REQUIRE_* rules show as hints on the sign-up form and are enforced by the server on every endpoint that sets a password (error PASSWORD_TOO_WEAK), so they can't be skipped by calling the API directly.
UI and Features
| Variable | Default | Allowed values | Effect |
|---|---|---|---|
ENABLE_THEME_TOGGLE | true | boolean | Shows the light/dark/system toggle. When off, the theme cookie is ignored and DEFAULT_THEME_MODE applies to everyone. |
Security
| Variable | Default | Allowed values | Effect |
|---|---|---|---|
CSP_MODE | enforce | enforce, report-only, off | Content Security Policy on production pages: enforced, reported in the console only, or not sent. Dev never sends one. See Content Security Policy. |
Adding Your Own
Declare your key in apps/web/env.ts, below the kit's keys, so kit updates (which change config/kit-env.ts) don't conflict with yours:
// apps/web/env.tsimport { defineEnv, string } from 'void/env';import { kitEnv } from './config/kit-env.ts';export default defineEnv({ ...kitEnv, // your keys ANALYTICS_WRITE_KEY: string(),});Then:
- Read it with
env.ANALYTICS_WRITE_KEYfromvoid/envinside a function in a*.server.tsfile (or a config getter). Runpnpm --filter web exec void env typesif the editor doesn't see the new key yet. - Add it to
apps/web/env.examplewith a safe local value. - Set it remotely with
void secret putin every environment, or give it a.default(...)(never for credentials). - If the browser needs it, add a field to
public-config.server.ts, and only if it is safe for anyone to see.
Helpers: string(), number(), boolean(), url(), email(), oneOf([...]), json<T>(), each with .optional() and .default(value). Any Standard Schema validator works too (the kit uses Zod for SITE_URL and BETTER_AUTH_SECRET). Imports inside env.ts must be relative with a .ts extension, or a package name.
Common Pitfalls
- Shell values replace
.envinpnpm dev. Setting any key in the shell (e.g.ACCOUNT_MODE=organizations-only pnpm dev) makes the dev server use the shell only and ignore.env. To override one value, export the whole file first:set -a; . apps/web/.env; set +a. vp previewpasses only the required keys (SITE_URL,PRODUCT_NAME,BETTER_AUTH_SECRET) to the Worker, so other keys use their defaults there. Run the local production preview withpnpm preview: it also passesDATABASE_URLfromapps/web/.env(deployed Workers use Hyperdrive instead). A plainvp previewcan't reach the database.void dbcommands readapps/web/.envonly, never the shell. To migrate another database, changeDATABASE_URLin.env.- Any
.env.*file inapps/webstops Void. Keep templates named without the leading dot (env.example). - No
.envmeans every request fails in dev, with the missing keys logged. Runpnpm kit:setupfirst. Don't copyenv.exampleby hand: itsBETTER_AUTH_SECRETis empty on purpose. process.envand module-levelenvreads don't work. Readenvinside functions.- An empty value counts as unset.
TURNSTILE_SITE_KEY=is the same as leaving it out.
Next: Account Modes →