Env Setting

Environment variable validation ด้วย Zod + server-only — fail fast ตอน startup, type-safe ตลอด project

Env Validation Overview

ทำไมต้อง validate environment variables? — Zod safeParse + fail fast pattern

ปัญหาถ้าไม่ validate env

Typo ใน env key — process.env.APIURL (ขาด _) → undefined → crash ตอน runtime
ลืมใส่ env ใน production — app พังหลัง deploy — ไม่รู้จนกว่า user จะเข้า
ไม่มี autocomplete — เดา key name → ต้องเปิด .env ดูทุกครั้ง

Zod validation แก้ปัญหาทั้งหมด

Zod schema — validate ครบทุก key ตอน startup
Type safety — autocomplete + compile-time error
Fail fast — พังตอน build/start ไม่ใช่ตอน user ใช้งาน

Server Env — server-only Guard

validate server-side env ด้วย Zod + ป้องกัน import ใน Client ด้วย server-only

Key Points

import 'server-only' — Client Component import ไฟล์นี้ → build error ทันที ป้องกัน secret leak
process.exit(1) — fail fast ตอน startup — ไม่ใช่ตอน user เข้าหน้า (ใช้ได้เฉพาะ server)
z.prettifyError() — แสดง error message อ่านง่าย — บอกชัดว่า key ไหนผิด/ขาด

Schema Fields (ตัวอย่างในโปรเจคนี้)

Key	Validation	Description
`API_URL`	string (url)	Backend API endpoint
`AUTH_SECRET`	string (min 10)	Secret สำหรับ sign JWT/session
`NODE_ENV`	enum + default	development \| production \| test

Client Env — NEXT_PUBLIC Gotcha

validate client-side env + gotcha สำคัญ: ต้อง reference process.env.NEXT_PUBLIC_XXX ทีละตัว

Gotcha: process.env ใน browser = {}

Next.js จะ inline ค่า NEXT_PUBLIC_* ตอน build — แต่ทำได้เฉพาะเมื่อเขียน process.env.NEXT_PUBLIC_XXX ตรงๆ ทีละตัว

WRONG

schema.safeParse(process.env)
// browser: process.env = {}
// ทุก key เป็น undefined!

CORRECT

schema.safeParse({
  NEXT_PUBLIC_BASE_URL:
    process.env.NEXT_PUBLIC_BASE_URL,
})
// Next.js inline ค่าจริง

ต่างจาก Server Env อย่างไร

ไม่มี server-only — ใช้ได้ทั้ง Server และ Client
ใช้ throw Error แทน process.exit — browser ไม่มี process.exit
ต้อง reference process.env.NEXT_PUBLIC_XXX ทีละตัว

.env File Structure

.env / .env.local / .env.example — ใครทำอะไร, priority, gitignore

Priority (สูง → ต่ำ)

#	File	Git	Description
3	`.env`	commit	ค่า default ทุก environment — commit ได้
1	`.env.local`	gitignore	Secret + override — ห้าม commit!
2	`.env.development`	commit	Override เฉพาะ dev mode
2	`.env.production`	commit	Override เฉพาะ production
-	`.env.example`	commit	Template สำหรับ team — commit ได้

Override ทำงานยังไง?

.env         → API_URL=http://localhost:3001
.env.local   → API_URL=https://staging.example.com

ผลลัพธ์: API_URL = "https://staging.example.com"
(.env.local override .env)

Type-safe Usage

วิธีเรียกใช้ serverEnv / clientEnv ใน Server Component, Client Component, Server Action

Server ComponentserverEnv

fetch(serverEnv.API_URL + "/api/features")

Client ComponentclientEnv

new WebSocket(clientEnv.NEXT_PUBLIC_SOCKET_URL)

Server ActionserverEnv

fetch(serverEnv.API_URL + "/api/auth/login")

ห้ามทำ

serverEnv ใน Client Component — build error — server-only guard
process.env.API_URL ตรงๆ — string | undefined — ไม่มี type safety
process.env.APIURL (typo) — ไม่มี error ตอน compile — พังตอน runtime