Pengelolaan Rahasia dan Variabel Lingkungan

Dalam aplikasi React, variabel lingkungan terbagi menjadi dua kelas: sisi server (tidak pernah dikirim ke peramban) dan sisi klien (disematkan dalam bundel JavaScript). Memahami kelas yang dimiliki setiap variabel adalah langkah pertama dalam pengelolaan rahasia, karena variabel sisi klien pada dasarnya bersifat publik setelah bundel diterapkan.

Dalam proyek Vite, hanya variabel yang diawali VITE_ yang disertakan dalam bundel klien. VITE_PUBLIC_API_URL=https://api.example.com dapat diakses dalam kode peramban melalui import.meta.env.VITE_PUBLIC_API_URL. Semua variabel lainnya dihapus dari bundel saat pembangunan dan tetap hanya tersedia di sisi server.

Di Next.js, awalan NEXT_PUBLIC_ mengekspos variabel ke JavaScript peramban. NEXT_PUBLIC_ANALYTICS_ID=UA-123 disematkan dalam bundel klien. Variabel tanpa awalan tersebut (seperti DATABASE_URL) hanya dapat diakses dalam kode sisi server (Komponen Server, rute API, dan Tindakan Server) dan tidak pernah dikirim ke peramban.

Variabel tanpa awalan tetap dapat diakses jika tidak sengaja diserialisasikan. Misalnya, jika Komponen Server meneruskan seluruh objek konfigurasi sebagai properti ke Komponen Klien, dan konfigurasi tersebut menyertakan DATABASE_URL, rahasia itu akan muncul dalam HTML yang dikirim ke peramban. Pengelolaan penerusan properti dan audit serialisasi secara cermat dapat mencegah hal ini.

Hal-hal berikut tidak boleh pernah muncul dalam bundel klien: string koneksi basis data dan kata sandi, kunci rahasia API pihak ketiga (kunci rahasia Stripe, kunci API OpenAI), kunci privat RSA/EC, rahasia penandatanganan JWT, serta token autentikasi layanan internal. Jika salah satunya diperlukan untuk panggilan API, teruskan panggilan tersebut melalui titik akhir server.

Pola Backend untuk Frontend (BFF) menempatkan lapisan server tipis di antara aplikasi React dan layanan eksternal yang sensitif. Klien memanggil /api/stripe/charge, server BFF menyertakan kunci rahasia Stripe lalu memanggil API Stripe, dan BFF hanya mengembalikan data respons yang diperlukan. Rahasia akan tetap berada di server secara permanen.

dotenv-vault mengenkripsi berkas .env Anda serta memungkinkan berbagi dan menerapkan konfigurasi dengan aman di berbagai lingkungan tanpa memasukkan rahasia teks biasa ke kontrol versi. Alternatif untuk produksi mencakup HashiCorp Vault (perusahaan), AWS Parameter Store (SSM), dan GCP Secret Manager—semuanya menyediakan pengambilan rahasia berbasis API saat program berjalan, bukan saat pembangunan.

Platform CI/CD (GitHub Actions, GitLab CI) menyediakan penyimpanan rahasia terenkripsi yang dapat diakses sebagai variabel lingkungan selama pembangunan. Simpan rahasia di GitHub Secrets, lalu rujuk dalam alur kerja sebagai ${{ secrets.STRIPE_SECRET_KEY }}. Rahasia disamarkan dalam log dan tidak pernah disertakan dalam artefak hasil pembangunan.

Next.js dan Vite mendukung beberapa berkas .env: .env (semua lingkungan), .env.local (penggantian lokal, diabaikan Git), .env.development, dan .env.production. Berkas lokal menggantikan nilai dari berkas bersama, sehingga memungkinkan konfigurasi khusus pengembang tanpa memengaruhi lingkungan lain.

Setelah pembangunan selesai, audit bundel JavaScript untuk mencari rahasia yang tidak sengaja terekspos. Jalankan grep -r "password|secret|api_key" dist/ atau gunakan alat khusus seperti analisis strings pada berkas hasil pembangunan. Beberapa rahasia, jika tidak sengaja disertakan, dapat dikenali dengan jelas dari formatnya (UUID, string base64, atau awalan kunci seperti sk_live_).

Setiap lingkungan dan setiap layanan seharusnya hanya memiliki akses ke rahasia yang dibutuhkannya. Klien React sama sekali tidak memerlukan rahasia—klien hanya boleh menerima pengenal publik. Server BFF hanya memerlukan rahasia yang dibutuhkan oleh API yang dipanggilnya. Lingkungan pengembangan sebaiknya menggunakan kunci API nonproduksi dengan izin dan batas pengeluaran yang terbatas.

Apa yang terjadi pada variabel lingkungan Next.js yang memiliki awalan NEXT_PUBLIC_?

Vite menggunakan VITE_ dan Next.js menggunakan NEXT_PUBLIC_ untuk mengekspos variabel ke bundel peramban. Semua variabel lainnya hanya tersedia di sisi server. Jangan pernah menyertakan kata sandi basis data, kunci rahasia API, atau rahasia penandatanganan JWT dalam kode klien. Gunakan pola BFF untuk meneruskan panggilan API sensitif. Gunakan dotenv-vault, AWS Parameter Store, atau GitHub Secrets untuk pengelolaan rahasia produksi. Audit bundel hasil pembangunan untuk mencari rahasia yang tidak sengaja terekspos.