Come funzionano le variabili d'ambiente in Next.js?

Question

Accepted Answer

Next.js carica le variabili d'ambiente dai file `.env`, con una regola di sicurezza importante: le variabili sono **server-only per impostazione predefinita**, e solo quelle con il prefisso `NEXT_PUBLIC_` sono esposte al browser.

## I file

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

## La regola del prefisso critico

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

Questa regola del prefisso è una **funzionalità di sicurezza**: impedisce di spedire accidentalmente password di database o segreti API al client. Una variabile senza prefisso semplicemente non esiste nei bundle del browser.

## Come vengono incorporate i valori NEXT_PUBLIC_

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

Poiché vengono inlineati al momento della compilazione, cambiare un valore `NEXT_PUBLIC_` richiede una **ricompilazione** — e non dovresti mai mettere veri segreti dietro il prefisso (sarebbero visibili nel bundle a chiunque).

## Best practice

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

## Perché è importante

Il modello server-only-per-impostazione-predefinita con l'opt-in `NEXT_PUBLIC_` è la protezione di Next.js contro la perdita di segreti al client — un errore comune e grave.

Comprendere quali variabili raggiungono il browser, che quelle pubbliche sono inlineate al momento della compilazione, e dove archiviare i segreti (`.env.local` ignorato da git) è essenziale sia per la funzionalità che per la sicurezza.