2025/04/30 2025/04/30

Astroで定数管理をするならvite.defineを設定する

Astroで個人ブログを開発するとき、サイトタイトル・共通のメッセージ・CSSクラス名など、繰り返し使う値が出てくる。

constants.tsを用意して定数管理をしていたが、ビルド後にファイルが残ることにいい気がしなかった。この記事では、定数用のファイルをつくらずに定数を管理する方法を紹介する。

vite.defineを使う

Astroは、開発サーバーの起動や本番用ビルドに内部的にViteを利用している。そして、Astroの設定ファイルであるastro.config.mjsでは、Viteの設定をカスタマイズできる。

Viteの設定オプションの一つにdefineがある。ビルド時にコード中の特定の識別子¹を、指定した値で置き換える機能を提供するものだ。

astro.config.mjsで定義した定数を、プロジェクト内のAstroファイルやJavaScript/TypeScriptファイルで、import文なしに利用できる。

astro.config.mjsの設定方法

1
import { defineConfig } from "astro/config";
2

3
export default defineConfig({
4
  vite: {
5
    define: {
6
      // サイトタイトルを定義
7
      SITE_TITLE: JSON.stringify("ウェブサイトの名前"),
8
      // CSSのIDを定義
9
      CSS_ID_CONTAINER: JSON.stringify("container"),
10
      // アイコンのサイズを定義
11
      ICON_SIZE: 64,
12
      // 環境変数を使って開発モードかどうかを判定
13
      IS_DEVELOPMENT: process.env.NODE_ENV === "development",
14
    },
15
  },
16
});

vite.defineで定数を設定するコード例

defineオブジェクトのキーが定数名になる。

文字列を定義する場合は、JSON.stringify()を使う必要がある。booleanやnumberはそのまま指定できる。

TypeScriptを使用している場合、defineで定義した定数はそのままでは型エラーとなる。型チェックを通すためには、型定義ファイルに定義を追加する必要がある。

1
declare const SITE_TITLE: string;
2
declare const CSS_ID_CONTAINER: string;
3
declare const ICON_SIZE: number;
4
declare const IS_DEVELOPMENT: boolean;

env.d.tsに定数を定義するコード例

エラーが出なくなり、import文なしでVSCodeなどのエディタの補完機能を利用できるようになる。

以下の画像では、わかりやすさのために__CONST__プリフィックスをつけて定数を定義した。

型定義ファイルに定数を自動で定義する

astro.config.mjsとenv.d.tsの2つのファイルで定数を管理するのは面倒だった。なので、astro.config.mjsが更新されたら、env.d.tsも更新されるようにする。

Viteの設定オプションの一つにpluginsがある。適切なプラグインをつくって登録すれば、astro.config.mjsが読み込まれたときにenv.d.tsファイルを書き換えられる。言い換えれば、両ファイルを同期できる。

ただし、著者はViteのプラグインについて詳しくないので、以下のコードは参考程度にしてほしい。

1
import type { ViteUserConfig } from "astro";
2
import fs from "fs";
3
import path from "path";
4

5
export default function generateEnvTypes() {
6
  const filename = "vite-plugin-define-constants";
7

8
  return {
9
    name: filename,
10
    config: (config: ViteUserConfig) => {
11
      // ファイルの読み込み
12
      const envPath = path.resolve(process.cwd(), "src/env.d.ts");
13
      const lines = fs.readFileSync(envPath).toString("utf-8").split("\n");
14

15
      // 生成された行が始まる印となる文字列
16
      const mark = `// generated by ${filename}.ts`;
17
      let startIndex = lines.findLastIndex((line) => line === mark);
18

19
      if (!config.define) {
20
        return;
21
      }
22

23
      // この配列を印の行の後に追加する
24
      const newLines = [];
25

26
      newLines.push(
27
        ...Object.entries(config.define)
28
          // .envとAstroフレームワークが定義したものを除外する
29
          .filter(
30
            ([key, value]) =>
31
              !(
32
                key.startsWith("import.meta.env") ||
33
                key.startsWith("__ASTRO_INTERNAL")
34
              )
35
          )
36
          .map(([key, value]) => `declare const ${key}: ${typeof value};`)
37
      );
38

39
      // 印が見つからなかった場合
40
      if (startIndex < 0) {
41
        // 印を先頭に追加する
42
        lines.push(mark, "\n", ...newLines);
43
      } else {
44
        // 印以降を置き換える
45
        lines.splice(startIndex + 1, lines.length - startIndex, ...newLines);
46
      }
47

48
      fs.writeFileSync(envPath, lines.join("\n"), "utf-8");
49

50
      return config;
51
    },
52
  };
53
}

1
import { defineConfig } from "astro/config";
2
import generateEnvTypes from "./vite-plugin-define-constants";
3

4
export default defineConfig({
5
  vite: {
6
    define: {…},
7
    plugins: [generateEnvTypes()],
8
  },
9
});

vite pluginを登録したコード例

プラグインを定義したファイルは./src/直下に配置した。

npm run devで開発サーバーを実行したときと、astro.config.mjsを保存したときにenv.d.tsが更新される。

定数管理するほかの方法と注意点

グローバルな定数を管理する方法は3つある。

.envファイルに定義する
astro.config.mjsのvite.defineに定義する
constants.tsに定義する

それぞれの特徴を比較したのが以下の表になる。

方法	特徴	デメリット
`.env`	APIキーなどの機密情報を定義するのに適している	`import.meta.env`でアクセスするためコードが長くなるデプロイ先で再定義が必要な場合がある
`vite.define`	ビルド後のファイルが減る	型定義が必要
`constants.ts`	型定義しなくても自然に扱える	ビルド後のファイルが増える

まとめ

vite.defineは、特にビルド時に値が確定する定数・グローバルにアクセスしたい設定値・公開してもいい環境変数と連動させたい値を管理するのに便利だ。

astro.config.mjsのvite.defineオプションを利用することは、定数管理の選択肢の一つだ。ビルド時に値を埋め込むので、シンプルに定数を扱える。

なお、vide.defineではstring・number・booleanだけでなく、objectも定義できるようだ。しかし、型定義ファイルを自動化したかったこともあり、面倒だったのでシンプルな形にした。

また、今回の方法を応用すれば、Lessファイル内の変数やCSSのクラス名も同期できた。

参考サイト

脚注

グローバル定数のようなもの ↩