Environment Variables

Pemuatan File .env

Bosia memuat variabel lingkungan dari file .env secara berurutan (yang belakangan menimpa yang sebelumnya):

1. .env
2. .env.local
3. .env.[mode] (misalnya .env.development, .env.production)
4. .env.[mode].local

Variabel lingkungan sistem selalu memiliki prioritas tertinggi — file .env tidak pernah menimpa variabel sistem yang sudah ada.

Nama vs nilai

Keempat file itu menentukan nilai untuk mode saat ini. Nama-nya dikumpulkan dari setiap file .env* di root proyek — termasuk .env.production, .env.test, dan .env.example — sehingga $env mengekspor daftar yang sama di dev, production, dan CI. Nama yang hanya dideklarasikan di file yang tidak dimuat mode saat ini akan bernilai kosong sampai ada yang mengisinya.

Artinya .env* berfungsi sebagai manifes: variabel yang nilainya berasal dari host Anda (Vercel, Docker, secret CI) tetap harus dideklarasikan di salah satu file .env* — biasanya .env.example — atau variabel itu tidak akan ada di $env dan type-check akan gagal.

Sistem Prefix

Nama variabel mengontrol di mana dan kapan variabel tersebut tersedia:

Prefix	Client	Server	Waktu	Contoh
PUBLIC_STATIC_	Ya	Ya	Build-time	PUBLIC_STATIC_APP_NAME
PUBLIC_	Ya	Ya	Runtime	PUBLIC_API_URL
STATIC_	Tidak	Ya	Build-time	STATIC_BUILD_ID
(tanpa prefix)	Tidak	Ya	Runtime	DATABASE_URL

• Variabel Build-time disematkan saat bosia build — mengubahnya memerlukan build ulang
• Variabel Runtime dibaca dari process.env pada setiap request
• Variabel Client diekspos secara aman ke browser; variabel Server tidak pernah meninggalkan server

Mengakses Variabel

Impor dari modul virtual $env:

import { PUBLIC_API_URL, DATABASE_URL } from "$env";

Hanya variabel yang dideklarasikan dalam file .env Anda yang tersedia melalui impor ini. Modul ini bersifat type-safe dengan deklarasi tipe yang dibuat secara otomatis.

Variabel Framework

Variabel-variabel ini dicadangkan oleh Bosia dan mengontrol perilaku framework. Semua nama yang diawali BOSIA_ juga dicadangkan. Nama yang dicadangkan tidak pernah muncul di $env, meski dideklarasikan di .env:

Variabel	Default	Deskripsi
PORT	9000	Port server
NODE_ENV	—	development atau production
BODY_SIZE_LIMIT	512K	Ukuran maksimal body request (mendukung K, M, G, Infinity)
IDLE_TIMEOUT	10	Idle timeout Bun.serve dalam detik (maks 255). Naikkan kalau API route memegang streaming response dengan jeda lama antar chunk — mis. endpoint chat AI yang menunggu tool call yang shell-out ke bunx bosia add. Set 0 untuk menonaktifkan.
BOSIA_REUSE_PORT	0	Set 1 untuk mengizinkan beberapa proses server berbagi satu port (SO_REUSEPORT), untuk clustering multi-proses yang disengaja. Default mati: kalau tidak, bosia start kedua diam-diam ikut menempel di port itu dan kernel membagi traffic ke dua build berbeda. Saat mati, server kedua menolak start dan keluar dengan exit code bukan nol.
BASE_PATH	"" (akar origin)	Memasang seluruh aplikasi di bawah prefix URL, misalnya /sso. Bosia melepasnya sebelum routing dan memasangnya kembali pada redirect, URL aset framework, cookie, dan router klien, sehingga rute dan event.url.pathname tetap tanpa prefix. Permintaan di luar base menghasilkan 404. Harus disetel untuk bosia build maupun bosia start. URL yang dibangun komponen Anda memerlukan ekspor base. Lihat Deployment › Memasang di Sub-Path.
MAX_INFLIGHT	Infinity	Batas lembut request bersamaan yang sedang diproses. Saat diset, request di atas batas langsung dapat 503 Service Unavailable dengan Retry-After: 1 sebelum kerja apa pun dilakukan — melindungi deploy container single-replica dari OOM saat ada lonjakan traffic. /_health selalu dikecualikan supaya liveness probe orkestrator tetap jalan saat aplikasi nge-shed load. Pilih nilai di bawah kapasitas memori container per render SSR bersamaan (titik awal aman: 500; tune dari situ).
WS_MAX_PAYLOAD	16M	Frame WebSocket terbesar yang diterima (format sama dengan BODY_SIZE_LIMIT, tanpa Infinity). Frame yang lebih besar menutup socket. Lihat WebSocket.
WS_IDLE_TIMEOUT	120	Detik tanpa frame sebelum Bun menutup WebSocket (0–960, 0 = tidak pernah). Bun mengirim ping sendiri, jadi peer yang hidup tidak akan kena.
WS_BACKPRESSURE_LIMIT	16M	Batas byte antrean untuk klien WebSocket yang lambat. Lewat batas ini send() membuang pesan dan mengembalikan 0; berhenti saat -1 dan tunggu drain supaya tidak sampai ke sana.
WS_COMPRESS	false	true menyalakan kompresi WebSocket (permessage-deflate). Membantu stream teks seperti output terminal; memakan CPU.
CACHE_KEYS	session,sid,auth,token,jwt,Authorization	Nama cookie/header yang ikut menentukan identitas cache respons, dipisahkan koma. Halaman dengan nilai berbeda untuk salah satu nama ini di-cache terpisah supaya konten per-user tidak bocor. Lihat Response cache.
CACHE_MAX_ENTRIES	500	Kapasitas LRU cache respons di memori. Set 0 untuk menonaktifkan cache sepenuhnya. Tiap entry menyimpan byte raw + gzip + brotli untuk satu pasangan URL/identity. Lihat Response cache.
CACHE_MAX_BYTES	104857600	Total memori (byte) untuk semua entry cache respons; yang paling lama dibuang duluan. Set 0 untuk membatasi dengan jumlah entry saja.
CACHE_IGNORE_PARAMS	utm_*,fbclid,gclid,…	Parameter query yang tidak masuk key cache halaman, jadi link ?utm_source=… mendapat halaman dari cache. nama* = prefix; mengisinya mengganti daftar; none = mati. Lihat Response Cache.
CACHE_WAIT_TIMEOUT	60000	Ms sebuah miss menunggu request lain yang sedang membangun entry yang sama sebelum membangun sendiri, jadi handler yang macet tidak memblokir URL-nya. Juga batas lama request data navigasi klien ikut menunggu request identik yang sedang berjalan (cache aktif atau tidak). Dihitung dari mulainya request pertama. Default METADATA_TIMEOUT + LOAD_TIMEOUT + 10000 kalau itu lebih lama. 0 atau Infinity = tunggu sampai selesai.
ASSET_CACHE_MAX_BYTES	52428800	Total memori (byte) untuk menyimpan file statis dan halaman prerender setelah request pertamanya. Set 0 agar selalu dibaca dari disk. Hanya Bun; diabaikan di Cloudflare Workers. Lihat Deployment.
ASSET_CACHE_MAX_FILE_BYTES	1048576	Ukuran file terbesar (byte) yang disimpan cache aset. File lebih besar selalu dibaca dari disk.
LOAD_TIMEOUT	30000	Timeout untuk load() dalam ms; waktu halaman termasuk await parent()-nya. Loader yang tidak pernah selesai diputus dengan 500, jadi URL-nya pulih. Bun menutup koneksi yang tidak mengirim apa pun selama IDLE_TIMEOUT (10 detik): naikkan juga untuk loader yang lebih lambat dari itu. 0 atau Infinity = tanpa timeout.
METADATA_TIMEOUT	10000	Timeout untuk metadata() dalam ms. 0 atau Infinity = tanpa timeout.
PRERENDER_TIMEOUT	5000	Timeout untuk setiap fetch prerender dalam ms (harus bilangan bulat, kalau tidak build gagal). Saat build hanya batas ini yang berlaku: LOAD_TIMEOUT, METADATA_TIMEOUT, MAX_INFLIGHT dan IDLE_TIMEOUT dimatikan untuk server prerender
PRERENDER_CONCURRENCY	6	Jumlah request prerender yang dijalankan bosia build sekaligus; halaman dan datanya dihitung dua, masing-masing menjalankan load()
CSRF_ALLOWED_ORIGINS	—	Origin yang diizinkan untuk CSRF, dipisahkan koma
CSRF_EXEMPT_PATHS	—	Path request yang dikecualikan dari pemeriksaan origin CSRF, untuk webhook server-ke-server yang tidak mengirim Origin/Referer. Dicocokkan persis atau pada batas path (/webhook mencakup /webhook/… tetapi bukan /webhooky). Rute yang dikecualikan melewati CSRF, jadi wajib mengautentikasi pemanggil sendiri (verifikasi token/signature webhook). Lihat Keamanan › Mengecualikan path webhook.
CORS_ALLOWED_ORIGINS	—	Origin yang diizinkan untuk CORS, dipisahkan koma
CORS_ALLOWED_METHODS	—	Method yang diizinkan, dipisahkan koma
CORS_ALLOWED_HEADERS	—	Header yang diizinkan, dipisahkan koma
CORS_EXPOSED_HEADERS	—	Header yang diekspos, dipisahkan koma
CORS_CREDENTIALS	false	Setel ke "true" untuk mengizinkan credentials
CORS_MAX_AGE	86400	Durasi cache preflight dalam detik
TRUST_PROXY	false	Percayai X-Forwarded-Host / X-Forwarded-Proto untuk origin publik: event.url, redirect, cek origin CSRF dan WebSocket, cookie Secure. Aktifkan hanya saat di belakang reverse proxy yang membersihkan header forwarded dari klien. Lihat Keamanan › Deployment di belakang reverse-proxy.
DISABLE_X_FRAME_OPTIONS	false	Setel ke "true" untuk menghilangkan header X-Frame-Options: SAMEORIGIN. Pakai saat aplikasi memang sengaja disematkan sebagai iframe oleh origin lain. Lihat Keamanan › Mematikan X-Frame-Options.
CSP_DIRECTIVES	—	Content-Security-Policy opsional. {nonce} diganti per request. Lihat Keamanan › Content Security Policy.

Variabel framework diakses melalui process.env secara langsung, bukan melalui $env.

Contoh File .env

# Public — available on client and server at runtime
PUBLIC_API_URL=https://api.example.com
PUBLIC_APP_NAME=My App

# Public static — inlined at build time
PUBLIC_STATIC_VERSION=1.0.0

# Private — server only
DATABASE_URL=postgres://localhost:5432/mydb
# Juga didukung (lihat /id/guides/database):
#   DATABASE_URL=mysql://user:pass@host:3306/mydb
#   DATABASE_URL=sqlite://./data/app.db
#   DATABASE_URL=sqlite://:memory:     # dev/test saja — terhapus saat restart
API_SECRET=sk_live_abc123

# Framework config
PORT=3000
BODY_SIZE_LIMIT=1M
CORS_ALLOWED_ORIGINS=https://app.example.com

Keamanan

Hanya variabel PUBLIC_* yang dideklarasikan dalam file .env yang dikirim ke client. Variabel yang hanya disetel sebagai variabel lingkungan sistem (tidak ada di file .env) tidak pernah diekspos ke browser, meskipun memiliki prefix PUBLIC_.