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 app
pnpm --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/postgres
SITE_URL=http://localhost:5173
PRODUCT_NAME=Makerkit
BETTER_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.ts calls defineEnv with the kit's keys (apps/web/config/kit-env.ts) plus yours. Read values with env from void/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 through useShared().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.local or .env.example) exists in apps/web, which is why the template is called env.example.
  • Fail fast. Values are checked by void env check, by void secret put and 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/web
pnpm exec void secret put PRODUCT_NAME # prompts for the value
pnpm exec void secret sync production-secrets.txt # bulk, dotenv format
pnpm exec void secret list # names only, never values
pnpm exec void env check --remote # required keys present remotely?
  • void deploy refuses 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_URL is never a Worker secret: deployed Workers connect through the HYPERDRIVE binding. Export it in the shell that runs void deploy (in Workers Builds, a build secret), which uses it to create the Hyperdrive config and run migrations. A Worker that already has a DATABASE_URL secret keeps bypassing Hyperdrive until you run void 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 deploy never uploads .env. Keep local credentials out of production secrets files.

Reference

Core

VariableDefaultAllowed valuesEffect
DATABASE_URLunsetPostgres connection URLLocal 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_URLrequiredURL; https unless localhost/127.0.0.1Canonical URL for links built without a request (emails, jobs).
PRODUCT_NAMErequiredstringProduct name in metadata, UI and emails.
BETTER_AUTH_SECRETrequiredstring, 32+ charactersSigns 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/dashboardpath 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_MODElightlight, dark, systemTheme for visitors without a theme cookie (or for everyone when the toggle is off).

Account Mode

VariableDefaultAllowed valuesEffect
ACCOUNT_MODEhybridpersonal-only, organizations-only, hybridPersonal accounts, organizations, or both. Derives most feature flags; see Account Modes.
ENABLE_PERSONAL_ACCOUNT_BILLINGfalsebooleanLets 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_SECRETunsetstringStripe 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)unsetstringDeclared 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_USER5whole number, 0–100How 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_DAYS7whole number, 1–30How many days an invitation's link works.
MAX_PENDING_INVITATIONS50whole number, 1–1000Pending (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

VariableDefaultAllowed valuesEffect
AUTH_PASSWORDtruebooleanEmail and password sign-in. Off: refused by the server too, not only hidden.
AUTH_MAGIC_LINKfalsebooleanEmail magic-link sign-in. Off: the Better Auth plugin isn't registered. See Authentication.
AUTH_EMAIL_OTPfalsebooleanSign-in with an emailed 6-digit code. Off: the Better Auth plugin isn't registered. See Authentication.
AUTH_PASSKEYfalsebooleanPasskey sign-in, passkeys added at /settings/security. Its table always exists, so switching it needs no migration. See Passkeys.
AUTH_TWO_FACTORfalsebooleanTwo-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_SECRETunsetstringGoogle 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_CHECKBOXfalsebooleanShows a terms checkbox on sign-up.
TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEYunsetstringCloudflare 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_LIMITtruebooleanBetter 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_CHARSfalsebooleanPassword must contain a character that isn't a letter or digit.
PASSWORD_REQUIRE_NUMBERSfalsebooleanPassword must contain a number.
PASSWORD_REQUIRE_UPPERCASEfalsebooleanPassword 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

VariableDefaultAllowed valuesEffect
ENABLE_THEME_TOGGLEtruebooleanShows the light/dark/system toggle. When off, the theme cookie is ignored and DEFAULT_THEME_MODE applies to everyone.

Security

VariableDefaultAllowed valuesEffect
CSP_MODEenforceenforce, report-only, offContent 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.ts
import { defineEnv, string } from 'void/env';
import { kitEnv } from './config/kit-env.ts';
export default defineEnv({
...kitEnv,
// your keys
ANALYTICS_WRITE_KEY: string(),
});

Then:

  1. Read it with env.ANALYTICS_WRITE_KEY from void/env inside a function in a *.server.ts file (or a config getter). Run pnpm --filter web exec void env types if the editor doesn't see the new key yet.
  2. Add it to apps/web/env.example with a safe local value.
  3. Set it remotely with void secret put in every environment, or give it a .default(...) (never for credentials).
  4. 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 .env in pnpm 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 preview passes 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 with pnpm preview: it also passes DATABASE_URL from apps/web/.env (deployed Workers use Hyperdrive instead). A plain vp preview can't reach the database.
  • void db commands read apps/web/.env only, never the shell. To migrate another database, change DATABASE_URL in .env.
  • Any .env.* file in apps/web stops Void. Keep templates named without the leading dot (env.example).
  • No .env means every request fails in dev, with the missing keys logged. Run pnpm kit:setup first. Don't copy env.example by hand: its BETTER_AUTH_SECRET is empty on purpose.
  • process.env and module-level env reads don't work. Read env inside functions.
  • An empty value counts as unset. TURNSTILE_SITE_KEY= is the same as leaving it out.

Next: Account Modes →