[Vite] index.html に環境変数を書き出す

この記事は ZOZO Advent Calendar 2022 #6 11日目の記事です。

12月もそろそろ折り返し、営業日換算では今年もあと10営業日で終わりという方もおられるかと思われる今日この頃、いかがお過ごしでしょうか。

今回は、フロントエンド用ビルドツール「Vite」の環境で、index.html に環境変数を書き出す方法をお伝えします。

Vite とは

Vite は、Vue.js の開発者 Evan You 氏により2020年に開発された、フロンドエンド用のビルドツールです。
Go 言語ベースで開発された esbuild を使用しており、従来の JavaScript ベースのビルドツールに比べめっちゃ早くビルドが行えます。
これにより、ローカルサーバーの立ち上げもあっという間に終わるので、気軽にローカルサーバーの再起動が行えます。

JSフレームワークやライブラリの導入も楽に行えます。
開発者が同じ Vue.js はもとより React（+ TypeScript） も、Vite プロジェクト作成時に設問に答える形でカンタンに環境の構築が行えます。

そんなお手軽＆爆速な Vite ですが、index.html に環境変数を書き出すには、2022/12 現在ちょっと一手間が要ります。

環境変数の書き出し

Vite にも環境変数を書き出す仕組み（e.g. import.meta.env.ENV_VAR_NAME）はありますが、index.html においては、その仕組みが使えません。

.env

VITE_SAMPLE = 'サンプルだよ'

Vite では環境変数名に VITE_ をプリフィックスとして付ける必要があります。

index.html

...
<title>import.meta.env.VITE_SAMPLE</title>
...

このように index.html に記述しても変数の中身は書き出されず、 <script> タグ内で記述しても参照できずにエラーとなります

index.html への環境変数の書き出し

方法としては、Vite のコンフィグにて transformIndexHtml フックを利用したプラグインを作成して対応します。
具体的には、作成したプラグインによって特定の文字列を対応した環境変数に置換します。

置換用プラグインの作成

今回は、EJS チックに %=環境変数名% という文字列を index.html に記述した際に、対応した環境変数の値に置換して書き出す設定を行います。
（< > を付けるとタグと認識されるため、付けずに %=...% とします）

index.html

...
<title>%=VITE_SAMPLE%</title>
...

Vite のコンフィグファイルを下記のように記述します。

vite.config.ts

import { defineConfig, loadEnv } from 'vite';

// https://vitejs.dev/config/
export default ({ mode }) => {
  const env = loadEnv(mode, process.cwd());

  const htmlPlugin = () => ({
    name: 'html-transform',
    transformIndexHtml: (html: string): string =>
      html.replace(/%=(.*?)%/g, (match, p1) => env[p1] ?? match),
  });

  return defineConfig({
    plugins: [
      htmlPlugin(),
    ],
    server: {
      host: true,
    },
  });
};

htmlPlugin というプラグインを作成し、 plugins に設定しています。
（plugins には使用するライブラリも適宜設定してください）

以上で設定は完了です。

これにより、loadEnv(mode, process.cwd()); によって環境変数がキーバリューの形で格納された定数に対し、%=(.*?)% でマッチした文字列をキーとして参照し、対応した値で該当箇所を置換します。
（対応した環境変数がなければ、マッチした文字列をそのまま書き出します）

余談

コンフィグ内に記述した環境変数を取り出す箇所を以下のようにすると、ビルド時に、参照している環境変数を列挙してログに表示することができるので「こんな値を参照しているんだ〜」というのが分かります。

vite.config.ts

  const env = { ...process.env, ...loadEnv(mode, process.cwd()) };
  console.log({ env });

以上