> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 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.

[Look up a configuration key](https://supastack.dev/docs/web/project-structure.md)

[Learn how to run a command and edit a file](https://supastack.dev/docs/web/terminal-basics.md)

```
corepack pnpm --filter @supastack/web dev
```


## 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
```


## Setup 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 missing
```


## Implementation 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.


## Next

[i18n module](https://supastack.dev/docs/modules/i18n.md)