Hoe werken omgevingsvariabelen in Next.js?

Question

Accepted Answer

Next.js laadt omgevingsvariabelen uit `.env` bestanden, met een belangrijke veiligheidsregel: variabelen zijn **standaard alleen op de server**, en alleen die met het voorvoegsel `NEXT_PUBLIC_` worden blootgesteld aan de browser.

## De bestanden

```text
.env                # loaded in all environments
.env.local          # local overrides — GITIGNORED (put secrets here)
.env.development    # only in `next dev`
.env.production     # only in production builds
```

## De kritieke voorvoegselregel

```bash
# .env.local
DATABASE_URL=postgres://...secret...   # server-only — NEVER sent to the browser
NEXT_PUBLIC_API_URL=https://api.example.com  # exposed to the browser
```

```tsx
// Server Component / Route Handler / Server Action — can read anything
const db = process.env.DATABASE_URL;          // ✅ works on the server

// Client Component — only NEXT_PUBLIC_* are available
"use client";
const api = process.env.NEXT_PUBLIC_API_URL;  // ✅ works
const secret = process.env.DATABASE_URL;      // ❌ undefined in the browser
```

Deze voorvoegselregel is een **veiligheidsfunctie**: het voorkomt dat je per ongeluk databasewachtwoorden of API-geheimen naar de client stuurt. Een variabele zonder voorvoegsel bestaat eenvoudigweg niet in browserbundels.

## Hoe NEXT_PUBLIC-waarden worden ingebed

```text
NEXT_PUBLIC_* are INLINED at BUILD time (baked into the JS bundle).
```

Omdat ze bij het bouwen inline worden geplaatst, vereist het wijzigen van een `NEXT_PUBLIC_` waarde een **herbouw** — en je moet nooit echte geheimen achter het voorvoegsel zetten (ze zouden zichtbaar zijn in de bundel voor iedereen).

## Aanbevolen procedures

```text
✓ Secrets (DB URLs, API keys) → no prefix, kept server-side, in .env.local (gitignored)
✓ Public config (public API base, analytics id) → NEXT_PUBLIC_
✓ Commit a .env.example documenting required vars (no real values)
```

## Waarom het belangrijk is

Het standaard alleen-op-de-server-model met de `NEXT_PUBLIC_` opt-in is Next.js's veiligheidsmaatregel tegen het lekken van geheimen naar de client — een veel voorkomende, ernstige fout.

Begrijpen welke variabelen de browser bereiken, dat openbare variabelen bij het bouwen inline worden geplaatst, en waar geheimen moeten worden opgeslagen (genegeerde `.env.local`) is essentieel voor zowel functionaliteit als beveiliging.