t3-env: Type-safe Environment Validation untuk TypeScript & Node.js

📌 Pendahuluan

Dalam pengembangan aplikasi modern — baik di Next.js, Hono, Bun, atau Node.js murni — kita sering menggunakan variabel environment (process.env) untuk menyimpan konfigurasi penting seperti:

• API key

• URL database

• Secret token

• Konfigurasi mode (production/development)

Namun, masalah klasik yang sering muncul adalah:

• ❌ Salah ketik nama variabel (API_URL vs APIURL)

• ⚠️ Variabel tidak didefinisikan di .env

• 🧩 Nilai environment tidak sesuai format (misalnya, bukan URL yang valid)

• 🔐 Variabel rahasia tidak sengaja terekspos ke sisi client

Masalah-masalah ini bisa berujung pada bug runtime, error production, atau kebocoran data sensitif.

Untuk itulah hadir t3-env — solusi dari tim T3 Stack (pencipta create-t3-app) untuk memberikan validasi, keamanan, dan type safety penuh terhadap variabel environment di proyek TypeScript.

---

⚙️ Apa itu t3-env?

t3-env adalah library yang:

• Menggunakan Zod untuk memvalidasi variabel environment

• Menghasilkan type definitions otomatis

• Membedakan antara server-side dan client-side

• Menjamin semua variabel environment terdefinisi dan valid sebelum aplikasi berjalan

Dengan kata lain, t3-env membuat process.env menjadi type-safe dan reliable.

---

💡 Perbandingan dengan dotenv

Kesimpulan:
t3-env bukan pengganti langsung dotenv, tapi pelengkap dan peningkatnya.
Jika framework-mu sudah memuat .env otomatis (seperti Next.js, Bun, Vite), maka tidak perlu menginstal dotenv lagi.

---

🚀 Instalasi

Jika kamu menggunakan Bun, Node.js, atau Hono:

npm install @t3-oss/env-core zod

Atau jika kamu memakai Next.js:

npm install @t3-oss/env-nextjs zod

---

🧩 Struktur Dasar Penggunaan

1. Import dan Definisikan Schema

import { createEnv } from "@t3-oss/env-core";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    SECRET_KEY: z.string().min(1),
  },
  client: {
    NEXT_PUBLIC_API_URL: z.string().url(),
  },
  runtimeEnv: process.env,
});

2. Akses dengan Type Safety

console.log(env.DATABASE_URL); // ✅ Sudah pasti string valid
console.log(env.NEXT_PUBLIC_API_URL); // ✅ Hanya bisa diakses jika di client schema

Jika ada kesalahan seperti:

• Variabel belum didefinisikan

• Format tidak sesuai schema
  maka t3-env akan langsung menampilkan error pada runtime dan di IDE TypeScript.

---

🔐 Pemisahan Client dan Server

Salah satu keunggulan besar t3-env adalah pemisahan konteks.

Server-only

Variabel seperti:

DATABASE_URL=postgresql://...
SECRET_KEY=abc123

Hanya didefinisikan di:

server: {
  DATABASE_URL: z.string().url(),
  SECRET_KEY: z.string(),
}

Client-only

Variabel dengan prefix NEXT_PUBLIC_:

NEXT_PUBLIC_API_URL=https://api.example.com

Hanya boleh didefinisikan di:

client: {
  NEXT_PUBLIC_API_URL: z.string().url(),
}

Jika kamu mencoba mengakses SECRET_KEY di browser, t3-env akan mencegahnya secara otomatis.

---

🧠 Validasi dan Error Handling

Misal file .env kamu tidak lengkap:

DATABASE_URL=
SECRET_KEY=supersecret

Maka t3-env akan memberikan error seperti:

❌ Invalid environment variables:
  DATABASE_URL: Expected URL, received ""

Artinya aplikasi tidak akan berjalan sebelum environment valid — memastikan keamanan sejak awal.

---

🔄 Integrasi dengan dotenv (Opsional)

Jika kamu menggunakan Node.js tanpa framework seperti Bun atau Next.js, tambahkan:

npm install dotenv

Lalu di file env.ts:

import "dotenv/config";
import { createEnv } from "@t3-oss/env-core";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    PORT: z.string().default("3000"),
  },
  runtimeEnv: process.env,
});

---

🧱 Contoh Implementasi di Hono + Bun

// src/env.ts
import { createEnv } from "@t3-oss/env-core";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    API_SECRET: z.string(),
  },
  runtimeEnv: process.env,
});

// src/index.ts
import { Hono } from "hono";
import { env } from "./env";

const app = new Hono();

app.get("/", (c) => c.text(`Connected to: ${env.DATABASE_URL}`));

export default app;

---

📈 Manfaat Penggunaan t3-env

1. Type safety penuh

   Tidak ada lagi process.env.MY_KEY as string.

2. Validasi otomatis

   Aplikasi gagal start jika ENV tidak valid.

3. Keamanan terjaga

   Variabel rahasia tidak bocor ke client.

4. Error cepat dan jelas

   Developer tahu persis variabel mana yang salah.

5. Terintegrasi mulus

   Cocok dengan Next.js, Hono, Bun, dan semua framework modern.

---

⚠️ Tips dan Best Practice

• Gunakan prefix NEXT_PUBLIC_ untuk variabel yang boleh diakses di frontend.

• Jangan definisikan variabel rahasia di client.

• Selalu commit file env.example (bukan .env!) untuk panduan environment rekan tim.

• Gunakan z.union() atau z.enum() untuk nilai pilihan seperti NODE_ENV.

Contoh:

NODE_ENV: z.enum(["development", "production", "test"]),

---

🧾 Kesimpulan

t3-env membawa revolusi kecil tapi penting dalam dunia JavaScript/TypeScript modern:
dari sekadar “membaca file .env” menjadi validasi environment yang aman, kuat, dan terintegrasi penuh dengan TypeScript.

Jika kamu sudah terbiasa menggunakan dotenv, migrasi ke t3-env akan membuat workflow-mu lebih:

• Aman

• Jelas

• Profesional

---

📚 Rangkuman Cepat

---