Configuration

Make one configuration change and check it

Start with a running Web app. In the editor open apps/web/.env.local; if it does not exist, copy .env.example there using the Web tutorial. For a harmless first check, find EMAIL_PROVIDER=local and leave it local. This setting sends product email to the local preview instead of a real inbox. Do not paste KEY=value lines into the terminal.

For each service you enable, follow that provider's setup guide, replace only the named values, save the file, stop the Web server with Ctrl + C and restart with the command below. If validation names a missing key, reopen this file and compare that key with the provider guide. Keep root .env synchronized only for values used by database migrations; copying it alone does not configure Next.js.

• Look up a configuration key
• Learn how to run a command and edit a file

corepack pnpm --filter @supastack/web dev

The settings you will actually edit first

.env.example at the repository root is the complete inventory of settings the kit understands; a name absent from that file does not exist. You only touch a handful at the start — the rest stay on their defaults until a provider guide asks for them.

Which file each app reads: root .env feeds the migration commands, apps/web/.env.local feeds the Next.js server, and apps/mobile/.env.local feeds Expo. Editing one file does not configure the others, so DATABASE_URL lives in both root .env and apps/web/.env.local.

• APP_URL — the address the app lives at; http://localhost:3000 locally, your domain in production.
• DATABASE_URL — the Postgres connection string migrations and the server share.
• AUTH_SECRET and CREDENTIAL_ENCRYPTION_KEY — generated secrets; node scripts/setup-env.mjs fills them for you (that helper ships in the Web repository and the All Platforms monorepo).
• The provider selectors — EMAIL_PROVIDER, AI_PROVIDER, BILLING_PROVIDER, JOB_PROVIDER, CAPTCHA_PROVIDER — each picks which adapter runs; the local/fake/off defaults need no account.
• Provider secrets such as RESEND_API_KEY or STRIPE_SECRET_KEY — add only when the matching provider guide tells you to.

Start with the environment example

The root .env.example is the configuration inventory. Shared validation lives in packages/config. Review the selected application environment and provider modes together; a local interface is not a production credential strategy.

The credential-free reference mode requires local/test application configuration and fake/local providers. Selecting a production provider changes the runtime requirements.

Keep secrets behind the API

Authentication secrets, database credentials, provider keys, Stripe secrets, and Trigger credentials are server-only. Never prefix them with NEXT_PUBLIC_ or EXPO_PUBLIC_. Do not print them during setup or include them in error responses.

The browser receives public configuration and allowed model aliases. Workspace ownership, entitlement decisions, budgets, and provider selection remain server-enforced.

Check a change before using it

Validate configuration through the existing config package and run the relevant deterministic tests. Use the separately opted-in provider smoke path when you are ready to verify real integrations.

corepack pnpm test
corepack pnpm check
corepack pnpm build