Next.js × dotenv-expandを使って環境変数を入れ子で柔軟に管理する方法

環境変数同士を参照したい場面、意外と多くありませんか?
Next.jsを用いた開発では、.env
ファイルで環境変数を管理することが一般的です。しかし、環境変数内で他の環境変数を使おうとすると、標準の.env
ファイル読み込み機能だけでは対応できません。
そんなときに便利なのが dotenv-expand
です。本記事では、このパッケージの導入方法から、具体的なユースケースまでを、丁寧に解説いたします。
環境変数のネスト定義を可能にするdotenv-expand
dotenv-expand
を利用することで、以下のように他の変数を参照した構文が使えるようになります。
envBASE_URL=https://example.com
API_ENDPOINT=${BASE_URL}/api
このような書き方を可能にする仕組みが dotenv-expand
の主な役割です。
Next.jsにdotenv-expandを導入する手順
まずは必要なパッケージのインストールです。Next.jsでは標準で dotenv
を利用していますが、それに加えて以下のように dotenv-expand
を追加します。
bashyarn add dotenv dotenv-expand
次に、環境変数を読み込むコードを、Next.jsの起動前に挿入します。
scripts/setup-env.js
というファイルを作成し、以下のように記述します。
jsconst dotenv = require('dotenv');
const dotenvExpand = require('dotenv-expand');
const fs = require('fs');
const path = require('path');
const envPath = path.resolve(__dirname, '../.env');
if (fs.existsSync(envPath)) {
const myEnv = dotenv.config({ path: envPath });
dotenvExpand.expand(myEnv);
}
そして、package.json
の dev
や build
スクリプトを以下のように修正します。
json{
"scripts": {
"predev": "node scripts/setup-env.js",
"dev": "next dev",
"prebuild": "node scripts/setup-env.js",
"build": "next build"
}
}
こうすることで、開発時もビルド時も dotenv-expand
によって変数展開された .env
の内容が利用されるようになります。
ユースケース紹介:現場で役立つパターン集
開発現場ではどのように活用できるのでしょうか?代表的なパターンをいくつか紹介します。
ユースケース名 | 内容 | 例 |
---|---|---|
APIエンドポイント統合 | BASE_URL を使って共通URLの管理 | API_URL=${BASE_URL}/api/v1 |
CDNのルート設定 | アセットURLをベースに画像パスなどを定義 | IMAGE_CDN=${CDN_BASE_URL}/images |
ログ出力設定 | 複数ログ設定をひとつのプレフィックスで統一管理 | LOG_PATH=${LOG_BASE}/system.log |
S3パス構成 | バケット名とリージョンからURLを構築 | S3_URL=https://${S3_BUCKET}.s3.${REGION}.amazonaws.com |
それぞれの構成において、重複を避け、環境依存の構造を柔軟に切り替えることができるのが大きな利点です。
Next.jsのpublicRuntimeConfigやserverRuntimeConfigとの併用
next.config.js
で publicRuntimeConfig
や serverRuntimeConfig
を用いて環境変数をアプリ内で参照する場合も、dotenv-expand
で展開された内容が活用可能です。
jsmodule.exports = {
publicRuntimeConfig: {
apiUrl: process.env.API_URL,
},
};
このように、setup-env.js
により .env
ファイルの変数が先に展開されているため、Next.jsの設定ファイルでも展開済みの値が利用できます。
まとめ:dotenv-expandで環境変数の管理をもっと便利に
dotenv-expand
を導入することで、環境変数内での他の変数参照が可能になります。- セットアップは簡単で、Next.jsの起動前に処理を加えるだけで利用可能です。
- 実際のユースケースとして、APIのURL管理、ログのパス設定、CDN構成などに役立ちます。
next.config.js
とも連携可能で、プロジェクト全体での一貫した変数管理が実現します。
環境変数が複雑になってきたときこそ、dotenv-expand
を活用することで保守性と可読性が向上します。ぜひ、今後のNext.jsプロジェクトで試してみてはいかがでしょうか。
Next.jsの記事Nextjs
- article
TypeScript 5.8 で強化された型推論!その裏で潜む 落とし穴と回避策
- article
【早見表】TypeScript Generics(ジェネリクス)の使用例と記法まとめ
- article
開発AIエディタ比較 Github Copilot vs Cursor vs Cline vs devin!それぞれの特徴や料金の違いを比較してみた
- article
【2025年5月版 早見表】TypeScript 5.7 tsconfig.jsonの主要オプションのまとめ
- article
【対処法】Cursorで発生する「Connection failed. If the problem persists ...」エラーの原因と対応
- article
Next.jsとEdge Runtimeを組み合わせて超低遅延サーバーレス表示を実現する方法