t3-env + Zod で .env を型安全にする設定方法

t3-env + Zod で .env を型安全にする設定方法

t3-env は環境変数を Zod スキーマで定義して型安全に使えるようにするライブラリです。.env の読み忘れや型ミスマッチをビルド時に検出できます。

---

早わかりまとめ

問題	t3-env + Zod で解決
process.env.FOO が string | undefined になる	スキーマで型を保証できる
必須変数の設定漏れに実行時まで気づかない	ビルド時・起動時にエラーで落とせる
バリデーションを自分で書く手間がある	Zod スキーマで一元管理できる

---

インストール

Next.js（App Router）の場合：

npm install @t3-oss/env-nextjs zod

Next.js 以外（Node.js など）の場合：

npm install @t3-oss/env-core zod

---

基本設定（Next.js）

// env.ts（プロジェクトルートに置く）
import { createEnv } from '@t3-oss/env-nextjs'
import { z } from 'zod'

export const env = createEnv({
  // サーバーサイドのみの環境変数
  server: {
    DATABASE_URL: z.string().url(),
    API_SECRET_KEY: z.string().min(1),
    NODE_ENV: z.enum(['development', 'test', 'production']),
  },

  // クライアント（ブラウザ）でも使う環境変数
  // Next.js では NEXT_PUBLIC_ プレフィックスが必要
  client: {
    NEXT_PUBLIC_API_URL: z.string().url(),
  },

  // 実際の環境変数を渡す
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    API_SECRET_KEY: process.env.API_SECRET_KEY,
    NODE_ENV: process.env.NODE_ENV,
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
  },
})

---

使い方

process.env.DATABASE_URL の代わりに env.DATABASE_URL を使います。

import { env } from '@/env'

// 型が保証されている（string 型、undefinedなし）
const dbUrl = env.DATABASE_URL

// クライアントコンポーネントでも使える
const apiUrl = env.NEXT_PUBLIC_API_URL

---

バリデーションエラーの例

必須の環境変数が未設定の場合、起動時にエラーが出ます。

❌ Invalid environment variables:
{
  DATABASE_URL: [ 'Required' ],
  API_SECRET_KEY: [ 'Required' ]
}

実行前に問題に気づけます。

---

よく使うスキーマパターン

server: {
  // 必須の文字列
  SECRET: z.string().min(1),

  // URL 形式
  DATABASE_URL: z.string().url(),

  // 数値（ポート番号など）
  PORT: z.coerce.number().default(3000),

  // 環境名
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),

  // オプション（未設定でも OK）
  OPTIONAL_KEY: z.string().optional(),

  // デフォルト値あり
  LOG_LEVEL: z.enum(['debug', 'info', 'error']).default('info'),
}

---

.env ファイルの例

DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
API_SECRET_KEY=super-secret-key
NODE_ENV=development
NEXT_PUBLIC_API_URL=http://localhost:3000/api

---

Node.js（Next.js 以外）での設定

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

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

---

まとめ

やること	コード
インストール	npm install @t3-oss/env-nextjs zod
スキーマ定義	createEnv({ server: { KEY: z.string() } })
環境変数を使う	env.DATABASE_URL（process.env の代わりに）
未設定を検出	ビルド時・起動時にエラーで教えてくれる
デフォルト値	z.string().default('value')
数値に変換	z.coerce.number()

Zod の基本的なスキーマ定義については「Zod 入門：z.object・z.infer・safeParse の使い方」を参照してください。