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）を使って better-env.ts を作成し、環境マッピング、env ファイルのターゲット、gitignore の動作を定義してください。

詳細はこちらをご覧ください。

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

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

CLI を使うと、初期化、同期、検証、リモート変数の管理を一貫したワークフローで行えるため、ローカル開発や CI 自動化に適しています。

リポジトリに合ったコマンドランナーを選んでください。

• npm／pnpm ベースのリポジトリでは、npx を使用してください（例：package-lock.json や pnpm-lock.yaml などのロックファイルがあり、npm／pnpm でスクリプトを実行する場合）。
• Bun ベースのリポジトリでは、bunx を使用してください（例：bun.lock があり、bun でスクリプトを実行する場合）。
• コマンドは、プロジェクトで既に使用されているパッケージマネージャー／ランタイムの規約に合わせてください。リポジトリですでに使われている場合を除き、複数のランナーを混在させないでください。

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

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

コマンドの動作は、意図に合わせて選んでください。

• 冪等性が必要な自動化やスクリプトには upsert を使用します。
• 重複するキーがある場合にエラーにするには add を使用します。
• キーが存在しない場合にエラーにするには update を使用します。
• リモートキーを削除するには delete を使用します。
• dotenv ファイルから一括で更新するには load を使用します。

詳細はこちらをご覧ください。

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