Environment Variables dan Konfigurasinya

Mengelola environment variables dalam proyek kami adalah hal yang penting, namun juga menantang. Proyek ini menggunakan environment variables untuk manajemen konfigurasi, memanfaatkan t3-env untuk environment variables yang type-safe dengan runtime validation. Ketika Anda menambahkan environment variables baru, Anda perlu memperbarui file .env.example dan file src/env.js untuk memastikan semuanya berjalan dengan benar.

File Konfigurasi

1. Skema Environment (src/env.js)

File env.js mendefinisikan skema dan aturan validasi untuk semua environment variables menggunakan Zod. Ini dibagi menjadi tiga bagian utama:

src/env.js

export const env = createEnv({
  // Server-side variables
  server: {
    DATABASE_URL: z.string().url(),
    NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
    BASE_URL: z.string().url(),
    BASE_PATH: z.string().optional(),
  },

  // Client-side variables (must be prefixed with NEXT_PUBLIC_)
  client: {
    NEXT_PUBLIC_POSTHOG_KEY: z.string(),
    NEXT_PUBLIC_POSTHOG_HOST: z.string().url(),
  },

  // Runtime environment mapping
  runtimeEnv: {
    // ... variable mappings
    DATABASE_URL: process.env.DATABASE_URL,
    NODE_ENV: process.env.NODE_ENV,
    BASE_URL: process.env.NEXT_PUBLIC_BASE_URL
      ? process.env.NEXT_PUBLIC_BASE_URL
      : process.env.NEXT_PUBLIC_VERCEL_URL
        ? `https://${process.env.NEXT_PUBLIC_VERCEL_URL}`
        : "https://himarpl.com",
    // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
    BASE_PATH: process.env.NEXT_PUBLIC_BASE_PATH || "",
    NEXT_PUBLIC_POSTHOG_KEY: process.env.NEXT_PUBLIC_POSTHOG_KEY,
    NEXT_PUBLIC_POSTHOG_HOST: process.env.NEXT_PUBLIC_POSTHOG_HOST,
  }
});

2. File Environment (.env)

Buat file .env pada root utama proyek dengan values yang spesifik pada environment Anda:

# Database Configuration
DATABASE_URL="your-database-url"

# Base URL Configuration
NEXT_PUBLIC_BASE_URL="http://localhost:3000"
NEXT_PUBLIC_BASE_PATH=""

# PostHog Analytics
NEXT_PUBLIC_POSTHOG_KEY="your-posthog-key"
NEXT_PUBLIC_POSTHOG_HOST="https://us.i.posthog.com"

Fitur Utama

• Type-Safety: Semua environment variables divalidasi saat build dan runtime
• Runtime Validation: Memastikan aplikasi Anda tidak dibangun dengan environment variables yang tidak valid
• Keamanan Client-Side: Pemisahan yang jelas antara server dan variabel klien
• Nilai Default: Cadangan untuk variabel tertentu ketika tidak disebutkan
• Penanganan String Kosong: String kosong diperlakukan sebagai undefined secara default

Panduan Penggunaan

1. Variabel Server-Side:

   • Diakses menggunakan env.VARIABLE_NAME
   • Tidak pernah diekspos ke klien
   • Contoh: env.DATABASE_URL

2. Variabel Client-Side:

   • Harus diawali dengan NEXT_PUBLIC_
   • Dapat diakses di kode server dan klien
   • Contoh: env.NEXT_PUBLIC_POSTHOG_KEY

3. Pengembangan:

   • Buat file .env lokal berdasarkan .env.example
   • Jangan pernah melakukan commit .env ke version control
   • Perbarui skema env.js saat menambahkan variabel baru

Contoh Penggunaan

src/server/db.ts

import { env } from "@/env";
import { PrismaClient } from "@prisma/client";

const createPrismaClient = () =>
  new PrismaClient({
    log:
      env.NODE_ENV === "development" ? ["query", "error", "warn"] : ["error"],
  });

const globalForPrisma = globalThis as unknown as {
  prisma: ReturnType<typeof createPrismaClient> | undefined;
};

export const db = globalForPrisma.prisma ?? createPrismaClient();

if (env.NODE_ENV !== "production") globalForPrisma.prisma = db;

Anda dapat mengakses environment variables pada kode seperti ini:

import { env } from "@/env.js";

// Server-side usage
const dbUrl = env.DATABASE_URL;

// Client-side usage
const posthogKey = env.NEXT_PUBLIC_POSTHOG_KEY;