Cum funcționează variabilele de mediu în Next.js?

Question

Accepted Answer

Next.js încarcă variabilele de mediu din fișierele `.env`, cu o regulă de securitate importantă: variabilele sunt **doar pe server în mod implicit**, și doar cele cu prefixul `NEXT_PUBLIC_` sunt expuse browserului.

## Fișierele

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

## Regula prefixului critic

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

Această regulă de prefix este o **caracteristică de securitate**: vă împiedică să trimiteți din greșeală parole de bază de date sau secrete API către client. O variabilă fără prefix pur și simplu nu există în packageurile browserului.

## Cum sunt încorporate valorile NEXT_PUBLIC

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

Deoarece sunt incorporate în timp de compilare, schimbarea unei valori `NEXT_PUBLIC_` necesită o **recompilare** — și nu trebuie niciodată să puneți secrete adevărate în spatele prefixului (ar fi vizibile în package pentru oricine).

## Cele mai bune practici

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

## De ce este important

Modelul doar pe server în mod implicit cu opțiunea `NEXT_PUBLIC_` este bariera Next.js împotriva scurgerii secretelor către client — o greșeală comună și serioasă.

Înțelegerea căreia variabile ajung la browser, că valorile publice sunt incorporate în timp de compilare și unde stocezi secretele (ignorat `.env.local`) este esențială atât pentru funcționalitate, cât și pentru securitate.