better-env

リポジトリで better-env を使用する

型安全な環境設定モジュール

完全な型安全性と明確なサーバー/パブリック境界を備えて TypeScript アプリケーションの環境変数を管理するには、このベストプラクティスに従ってください。

better-env は、型付きの環境モジュールを定義するために configSchema をエクスポートし、それらを機能レベルの config.ts ファイル（たとえば src/lib/auth/config.ts や src/lib/database/config.ts）に配置することを推奨しています。

詳細:

• references/config-schema.md

現在の環境で全ての環境変数の存在を検証する

dev、build、デプロイの各ステップの前に、環境変数の検証を早い段階で実行して、値の欠落や無効を素早く検出してください。

better-env validate --environment <name> は、Next.js のセマンティクスで .env* ファイルを読み込み、src/lib/*/config.ts モジュールを検出し、configSchema モジュールで宣言された全ての変数をチェックします。

dotenv ファイルに、設定モジュールから参照されていないキーが意図的に含まれている場合は、better-env.ts に環境ごとの抑制設定を追加してください:

environments.<env>.ignoreUnused: string[]

これらは validate の実行中に、選択されたローカル環境のみを抑制します。 アダプターのデフォルトは自動的にマージされます。Vercel の場合、 VERCEL_OIDC_TOKEN は development、preview、production でデフォルトで無視されます。

詳細:

• references/env-validation.md

ローカルファイルとホスト型プロバイダー間のランタイム同期を設定する

ランタイム設定を使用して、安全なデフォルトを維持しながら、ローカルの dotenv ターゲットをプロバイダー環境と整合させてください。

defineBetterEnv(...) とアダプター（vercelAdapter、netlifyAdapter、railwayAdapter、cloudflareAdapter、flyAdapter、または convexAdapter）を使用して better-env.ts を作成してください。

標準的な Vercel のセットアップでは、最小限の設定を推奨します:

export default defineBetterEnv({ adapter: vercelAdapter() });

アダプターのデフォルトを重複させるだけの場合は、environments ブロックを追加しないでください。 environments は、カスタムマッピング、カスタム env ファイル、または環境ごとの ignoreUnused の動作が意図的に必要な場合にのみ追加してください。

詳細:

• references/config.md
• references/runtime.md

日常的な環境操作には CLI を使用する

CLI は、初期化、同期、検証、およびリモート変数管理のための一貫したワークフローを提供し、ローカル開発や CI 自動化に最適です。

リポジトリに合わせてコマンドランナーを選択してください:

• npm/pnpm ベースのリポジトリ（たとえば package-lock.json や pnpm-lock.yaml のようなロックファイルがあり、スクリプトを npm/pnpm で実行する場合）では npx を使用してください。
• Bun ベースのリポジトリ（たとえば bun.lock があり、スクリプトを bun で実行する場合）では bunx を使用してください。
• コマンドはプロジェクトの既存のパッケージマネージャー/ランタイムの慣習に合わせてください。リポジトリがすでにそうでない限り、ランナーを混在させないでください。

リポジトリでの推奨フロー:

1. better-env init を一度実行して、アダプターの前提条件を確認します。
2. better-env pull --environment <name> を実行して、ローカルの env ファイルを同期します。
3. アプリの起動/ビルドの前に better-env validate --environment <name> を実行します。
4. リモート env の変更には add、upsert、update、delete、load を使用します。

コマンドの動作は意図的に選択してください:

• 冪等な自動化やスクリプトには upsert
• 重複キーを失敗させたい場合には add
• キーの欠落を失敗させたい場合には update
• リモートキーを削除するには delete
• dotenv ファイルからのバッチ更新には load

詳細:

• references/cli.md
• references/vercel-adapter.md