📌 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:
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
| Aspek | dotenv | t3-env |
| Fungsi utama | Membaca file .env ke process.env | Memvalidasi dan memberi tipe pada variabel ENV |
| Level keamanan | Tidak ada validasi | Validasi ketat menggunakan zod |
| TypeScript support | Tidak ada (semua `string | undefined`) |
| Beda client/server | Tidak ada | Ada pemisahan jelas |
| Error handling | Silent (jika variabel hilang) | Throw error langsung |
| Digunakan di | Semua proyek Node.js | Proyek TS/JS modern seperti Next.js, Hono, Bun, dkk |
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);
console.log(env.NEXT_PUBLIC_API_URL);
Jika ada kesalahan seperti:
🔐 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:
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
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,
});
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
Type safety penuh
Tidak ada lagi process.env.MY_KEY as string.
Validasi otomatis
Aplikasi gagal start jika ENV tidak valid.
Keamanan terjaga
Variabel rahasia tidak bocor ke client.
Error cepat dan jelas
Developer tahu persis variabel mana yang salah.
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:
📚 Rangkuman Cepat
| Fitur | dotenv | t3-env |
Load .env file | ✅ | ❌ (bisa lewat dotenv) |
| Validasi nilai | ❌ | ✅ (via Zod) |
| Type safety | ❌ | ✅ |
| Pemisahan client/server | ❌ | ✅ |
| Cocok untuk Next.js / Bun / Hono | ⚠️ | ✅ |
| Throw error bila salah | ❌ | ✅ |
