# Environment Variables Reference

> Every environment variable the kit declares, how to set them locally and in deployed environments, and how to add your own.

*Canonical: https://makerkit.dev/docs/void-cloudflare/configuration/environment-variables*

---

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](./overview).

## Quick Start

```bash
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.

```bash
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.

```bash
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](../deployment/overview#staging-and-previews)).
- `void deploy` never 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](./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](../authentication/overview). |
| `AUTH_EMAIL_OTP` | `false` | boolean | Sign-in with an emailed 6-digit code. Off: the Better Auth plugin isn't registered. See [Authentication](../authentication/overview). |
| `AUTH_PASSKEY` | `false` | boolean | Passkey sign-in, passkeys added at `/settings/security`. Its table always exists, so switching it needs no migration. See [Passkeys](../authentication/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](../authentication/two-factor). |
| `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](../authentication/oauth). |
| `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](../authentication/captcha). |
| `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](../security/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:

```ts
// 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 →](./account-modes)
