# 3. Configure environment variables

> Configure local and Vercel environment variables while keeping Supabase secret keys server-only.

# Configure environment variables

Configure environment variables before expecting a production deployment to work. The project may have an initial Vercel deployment already, but it must be redeployed after production values are present.

## Start from the application contract

Copy the application's example file and fill every required value:

```bash
cp .env.local.example .env.local
```

Do not copy a `.env.local` file from another product. Keep `.env.local` out of version control and use the exact variable names declared by the current starter.

Run `supacharger doctor` to check the expected public variable names, then search the application contract for any product-specific server variables.

## Supabase values

Supabase projects now provide publishable and secret API keys. Existing projects may still expose legacy `anon` and `service_role` keys for compatibility. Use the key names expected by the installed Supacharger version.

| Kind | Typical purpose | Exposure |
| --- | --- | --- |
| Project URL | Browser and server Supabase clients | May be public |
| Publishable key or legacy `anon` key | Browser client, constrained by grants and RLS | May be public |
| Secret key or legacy `service_role` key | Trusted server administration only | Server only |
| Database password or connection string | CLI, migrations, or a trusted server when required | Server/developer tooling only |

Any variable prefixed with `NEXT_PUBLIC_` is included in the browser bundle. Never place a Supabase secret key, legacy service-role key, database password, Stripe secret, SMTP password, or webhook secret in such a variable.

## Canonical site URL

Set the local value to the exact origin used by the local application:

```dotenv
NEXT_PUBLIC_SITE_URL=http://localhost:3000
```

Set Vercel Production to the canonical HTTPS origin, without a path:

```dotenv
NEXT_PUBLIC_SITE_URL=https://app.example.com
```

Supacharger treats `NEXT_PUBLIC_SITE_URL` as the runtime source of truth for authentication destinations. Do not depend on an implicit localhost or Vercel fallback in production.

## Configure Vercel scopes

In **Vercel → Project → Settings → Environment Variables**:

1. Add the hosted Supabase URL and the matching publishable key.
2. Add only the server credentials actually required by the application.
3. Set `NEXT_PUBLIC_SITE_URL` separately for Production, Preview, and Development where their origins differ.
4. Add Stripe, email, analytics, and application-specific variables only when those features are enabled.
5. Mark sensitive values as sensitive where the Vercel plan and workflow support it.
6. Confirm no value was copied from a different Supabase environment.

Preview deployments need an explicit policy. Either connect them to a dedicated staging Supabase project or deliberately allow preview callback URLs in the production project. A staging project is safer when previews can modify data.

## Pulling variables locally

If Vercel is the managed source for development values, use Vercel's environment pull workflow carefully. Review the destination before overwriting an existing `.env.local`, and do not pull production secrets onto a machine that should not hold them.

## Completion check

- Local development contains no blank or placeholder required values.
- Vercel Production has the production Supabase project values.
- Preview and Production do not accidentally share secrets or data.
- No server secret uses a `NEXT_PUBLIC_` name.
- `.env.local` is ignored by Git.

Next: [Deploy and establish URLs](./04-deploy-and-urls.md).