For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/modules/config.md (or send Accept: text/markdown).
Environment and config
One validated schema for the whole workspace.
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.
corepack pnpm --filter @supastack/web devStart 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 buildSetup and configuration
packages/config is the single place that parses process.env: a zod schema produces a typed ServerConfig and PublicConfig, and provider selection is expressed as kinds — providers.ai, providers.billing, providers.email, providers.jobs, providers.storage each resolve to a named adapter plus its required fields.
Enabling a provider makes its credentials required: turning on a social sign-in, the s3 storage kind, or the resend email kind fails startup with the missing variable named, rather than a runtime surprise later.
STORAGE_PROVIDER=s3
STORAGE_BUCKET=kit
STORAGE_ENDPOINT=https://s3.example
STORAGE_PUBLIC_BASE_URL=https://cdn.example
# → config rejects the env if a required field is missingImplementation workflow
Read config through parseServerConfig at the server boundary and pass the typed value inward — do not touch process.env inside feature code. Public config is a separate, deliberately small object that is safe to serialize to the client.
Product-specific env belongs to the consuming product's own schema. Resist growing the kit schema for one product's needs.
Verification and troubleshooting
Run the config package tests after changing the schema, and check that a missing required variable names itself in the error. An env that parses locally but not in production usually means an undocumented required field.