Node.js, Package, dan Ekosistemnya · 7/7

Environment variable dan rahasia

Konfigurasi yang berbeda tiap mesin — dan aturan yang menjaga API key-mu tidak sampai ke browser.

Baca 22 menit

Setelah pelajaran ini kamu bisa

Menjelaskan apa itu environment variable dan kenapa konfigurasi tinggal di sana
Memakai file `.env`, dan tahu file env mana yang boleh di-commit
Menjelaskan tepat variable mana yang sampai ke browser di Next.js
Memvalidasi konfigurasi saat startup alih-alih crash belakangan

Environment variable adalah nilai yang diberikan sistem operasi ke programmu saat ia mulai. Inilah cara kode yang sama berperilaku berbeda di laptopmu dan di production tanpa satu baris pun berubah.

Aturan yang menentukan apa yang layak di sana: apa pun yang berbeda antar environment, dan apa pun yang rahasia. URL database itu berbeda. API key itu rahasia. Tarif pajak bukan keduanya — itu logika bisnis dan tempatnya di kode, di mana ia bisa direview dan diuji.

// Reading them. Always a string, or undefined.
const databaseUrl = process.env.DATABASE_URL;
const port = Number(process.env.PORT ?? 3000);

// This project's own example, from features/db/index.ts:
const path = process.env.DATABASE_PATH ?? join(process.cwd(), "data", "app.db");

Coba sendiri

Jebakan falsy dan cara membaca yang benar. Setiap kesalahan ini pernah sampai ke production di suatu tempat.

// Pretend this is process.env - values are always strings.
const env = {
  DEBUG: "false",
  PORT: "3000",
  FEATURE_FLAG: "",
  MISSING: undefined,
};

console.log("--- the trap ---");
console.log('if (env.DEBUG) is', Boolean(env.DEBUG), '<- "false" is a non-empty string!');
console.log('env.PORT + 1 gives', env.PORT + 1, "<- string concatenation");

console.log("");
console.log("--- doing it properly ---");
function readBoolean(value, fallback = false) {
  if (value === undefined || value === "") return fallback;
  return value === "true" || value === "1";
}
function readNumber(value, fallback) {
  const n = Number(value);
  return Number.isFinite(n) ? n : fallback;
}
function requireValue(value, name) {
  if (value === undefined || value === "") {
    throw new Error("Missing required environment variable: " + name);
  }
  return value;
}

console.log("DEBUG   ->", readBoolean(env.DEBUG));
console.log("PORT    ->", readNumber(env.PORT, 3000), typeof readNumber(env.PORT, 3000));
console.log("FLAG    ->", readBoolean(env.FEATURE_FLAG, true), "(empty falls back)");

try {
  requireValue(env.MISSING, "DATABASE_URL");
} catch (error) {
  console.log("startup check ->", error.message);
}

Hasil

Tekan Jalankan untuk melihat hasilnya.

Ini jalan di browser kamu, di dalam sandbox. Apa pun yang kamu tulis di sini tidak bisa merusak situs.

File .env

Mengatur variable manual setiap kali itu tidak praktis, jadi alat-alat membacanya dari file .env. Next.js melakukannya otomatis — tidak butuh library.

bash

# .env.local  - your machine, never committed
DATABASE_PATH=./data/dev.db
SESSION_SECRET=a-long-random-string-for-development
NEXT_PUBLIC_SITE_NAME=Fullstack Learning Path

File	Tujuan	Di-commit?
`.env.example`	Template yang mendaftar nama yang dibutuhkan, tanpa nilai asli	Ya
`.env.local`	Nilai asli di mesinmu, termasuk rahasia	Jangan pernah
`.env.development`	Default non-rahasia bersama untuk dev	Biasanya ya
`.env.production`	Default non-rahasia bersama untuk prod	Biasanya ya
`.env`	Default untuk semua environment	Hanya kalau tidak ada rahasia di dalamnya

Coba sendiri

Parser `.env`. Perhatikan kasus-kasus tepinya — komentar, tanda kutip, baris kosong, dan nilai yang mengandung tanda sama dengan.

function parseEnv(text) {
  const result = {};

for (const rawLine of text.split("\n")) {
    const line = rawLine.trim();
    if (line === "" || line.startsWith("#")) continue;   // skip blanks, comments

const equals = line.indexOf("=");
    if (equals === -1) continue;                          // no key: ignore

const key = line.slice(0, equals).trim();
    let value = line.slice(equals + 1).trim();            // keep later = signs

// Strip one matching pair of surrounding quotes.
    const quoted =
      (value.startsWith('"') && value.endsWith('"')) ||
      (value.startsWith("'") && value.endsWith("'"));
    if (quoted && value.length >= 2) value = value.slice(1, -1);

result[key] = value;
  }
  return result;
}

const file = [
  "# database",
  "DATABASE_PATH=./data/dev.db",
  "",
  'SESSION_SECRET="a b c with spaces"',
  "CONNECTION=postgres://user:pass@host/db?ssl=true",
  "EMPTY=",
  "  SPACED  =  value  ",
  "not-a-pair",
].join("\n");

const parsed = parseEnv(file);
for (const [key, value] of Object.entries(parsed)) {
  console.log(key.padEnd(16), JSON.stringify(value));
}

Hasil

Tekan Jalankan untuk melihat hasilnya.

Ini jalan di browser kamu, di dalam sandbox. Apa pun yang kamu tulis di sini tidak bisa merusak situs.

Batas NEXT_PUBLIC_

Ini paragraf terpenting di pelajaran ini. Di Next.js, variable yang namanya diawali NEXT_PUBLIC_ akan disubstitusikan ke bundle browser saat build. Sisanya tetap di server.

// Server-only. Available in Server Components, Server Actions, Route Handlers.
process.env.SESSION_SECRET      // never sent to the browser
process.env.DATABASE_URL

// Public by design. Embedded into the JavaScript every visitor downloads.
process.env.NEXT_PUBLIC_SITE_NAME
process.env.NEXT_PUBLIC_ANALYTICS_ID

// The mistake:
"use client";
const secret = process.env.SESSION_SECRET;   // undefined - and that is the
                                             // framework protecting you

Nilainya undefined di client component itu fitur. Bug-nya adalah saat ada yang "memperbaikinya" dengan mengganti nama variable-nya jadi NEXT_PUBLIC_SESSION_SECRET.

// features/config/env.ts - imported early, so it runs at startup.
import "server-only";

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error("Missing required env var: " + name);
  return value;
}

export const config = {
  sessionSecret: required("SESSION_SECRET"),
  databasePath: process.env.DATABASE_PATH ?? "./data/app.db",
  isProduction: process.env.NODE_ENV === "production",
} as const;

Satu tempat yang mengetahui semua variable, diperiksa sekali. Semua bagian lain mengimpor config dan mendapat nilai bertype alih-alih string | undefined.

Tugas praktik

Di proyek ini, buat .env.local berisi DATABASE_PATH=./data/experiment.db, lalu jalankan bun run dev, daftarkan sebuah akun, dan pastikan ada file baru muncul di data/experiment.db. Lalu cek .gitignore dan pastikan .env.local dan /data/ sudah diabaikan — lalu jelaskan dalam satu kalimat kenapa masing-masingnya begitu.

Hasil yang diharapkan

File database baru di path yang kamu pilih, dan kedua entri sudah ada di .gitignore.

Cek pemahaman

DEBUG=false ada di .env-mu. Apa yang dilakukan if (process.env.DEBUG) { ... }?

Melewati block-nya, karena nilainya falseMenjalankan block-nya, karena "false" adalah string tidak kosong sehingga truthyMelempar error, karena nilainya tidak bisa dipaksa jadi boolean

Pilih jawaban dulu