Jinsi variables za mazingira zinavyofanya kazi katika Next.js?

Question

Accepted Answer

Next.js inapakia variables za mazingira kutoka kwa faili za `.env`, na kwa kanuni muhimu ya usalama: variables ni **kwa ajili ya server tu kwa chaguo-msingi**, na tu zile zilizo na kiambishi `NEXT_PUBLIC_` zinatolewa kwa browser.

## Faili

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

## Kanuni ya kiambishi muhimu

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

Kanuni hii ya kiambishi ni **sifa ya usalama**: inakuzuia kutoka kutuma nenosiri la database au siri za API kwa mteja. Variable bila kiambishi haipo tu katika bundles za browser.

## Jinsi thamani za NEXT_PUBLIC_ zinajumuishwa

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

Kwa sababu zinajumuishwa wakati wa kujenga, kubadilisha thamani ya `NEXT_PUBLIC_` kunahitaji **kujenga tena** — na kamwe usiweka siri halisi nyuma ya kiambishi (zingezikuwa zinaonekana kwenye bundle kwa kila mtu).

## Maadhimisho ya kawaida

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

## Kwa nini ni muhimu

Mfano wa server-tu-kwa-chaguo-msingi na ushirikiano wa `NEXT_PUBLIC_` ni kuzuia kwa Next.js kutokana na kuota siri kwa mteja — kosa la kawaida na linalotaka kuzingatiwa.

Kuelewa ni variables gani zinakwenda kwa browser, kwamba thamani za umma zinajumuishwa wakati wa kujenga, na mahali ambapo siri zimahifadhiwa (`.env.local` inayokamatwa) ni muhimu kwa utekelezaji na usalama.