Svelte入門：リファレンス $app/environment

よっしー

こんにちは。よっしーです(^^)

今日は、SvelteKitのリファレンスについて解説しています。

背景
$app/environment
おわりに

背景

SvelteKitのリファレンスについて調査する機会がありましたので、その時の内容を備忘として記事に残しました。

$app/environment

import { browser, building, dev, version } from '$app/environment';

この行は $app/environment モジュールから4つの値をインポートしています。これは SvelteKit の特別なモジュールで、アプリケーションの実行環境に関する情報を提供します。

browser – アプリケーションがブラウザで動作しているかどうかを示すブール値。true ならブラウザ環境、false ならサーバー環境。
building – アプリケーションがビルド時に実行されているかどうかを示すブール値。静的サイト生成（SSG）時に true になります。
dev – アプリケーションが開発モードで実行されているかどうかを示すブール値。開発サーバーで実行中は true、本番環境では false になります。
version – アプリケーションのバージョン文字列。通常は package.json の version フィールドから取得されます。

これらの値は条件付きロジックを実装するのに便利です。例えば、開発環境でのみ特定の機能を有効にしたり、サーバーサイドとクライアントサイドで異なる処理を行ったりする場合に使用できます。

browser

アプリがブラウザで実行されている場合に true となります。

const browser: boolean;

解説

この変数は SvelteKit アプリケーションがブラウザ環境で実行されているかどうかを示すブール値です。

ブラウザ環境（クライアントサイド）での実行時: true
サーバー環境（サーバーサイドレンダリング時）での実行時: false

この変数は、ブラウザ固有の API（window、document など）を使用する前にチェックする場合や、サーバーサイドとクライアントサイドで異なる処理を行いたい場合に特に便利です。

使用例

import { browser } from '$app/environment';

// ブラウザでのみ localStorage を使用
if (browser) {
  const savedValue = localStorage.getItem('key');
  // ...
}

building

SvelteKit は build ステップ中にアプリを実行して解析します。この処理中は building は true になります。これはプリレンダリング中にも適用されます。

const building: boolean;

解説

この変数は SvelteKit アプリケーションがビルドプロセス中に実行されているかどうかを示すブール値です。

ビルド時（npm run build など）: true
通常の実行時（開発サーバーや本番環境）: false

この値は特に静的サイト生成（SSG）やプリレンダリングの段階で重要です。ビルド時にのみ特定の処理を行いたい場合や、通常の実行時と異なる振る舞いをさせたい場合に使用できます。

例えば、開発時や本番実行時には実際の API をコールするが、ビルド時には静的なデータを使用するといった使い分けが可能になります。

使用例

import { building } from '$app/environment';

async function getData() {
  if (building) {
    // ビルド時は静的データを返す
    return staticData;
  } else {
    // 通常実行時は API をコール
    return fetch('/api/data').then(r => r.json());
  }
}

dev

開発サーバーが実行中かどうかを示します。これは NODE_ENV や MODE と必ずしも一致するとは限りません。

const dev: boolean;

解説

この変数は SvelteKit アプリケーションが開発モードで実行されているかどうかを示すブール値です。

開発サーバー実行時（npm run dev など）: true
本番環境や本番ビルドを使用している場合: false

この変数は主に開発時にのみ特定の機能を有効にしたい場合に使用します。例えば、デバッグ情報の表示、開発限定のツールの読み込み、パフォーマンスに影響するが開発中に便利な機能の有効化などです。

注意点として、この値は環境変数の NODE_ENV や Vite の MODE と必ずしも一致するとは限らないと明記されています。そのため、環境固有の動作を制御する場合は適切な変数を選択することが重要です。

使用例

import { dev } from '$app/environment';

// 開発環境でのみデバッグパネルを表示
if (dev) {
  showDebugPanel();
}

// 開発環境と本番環境で異なるエンドポイントを使用
const API_URL = dev 
  ? 'http://localhost:3000/api' 
  : 'https://production.example.com/api';

version

config.kit.version.name の値です。

const version: string;

解説

この変数は SvelteKit プロジェクトに設定されたバージョン文字列を表します。

この値は SvelteKit の設定ファイル（通常は svelte.config.js）内の kit.version.name の設定から取得されます。指定されていない場合は、プロジェクトの package.json の version フィールドがデフォルト値として使用されることが多いです。

この変数はアプリケーションのバージョンを表示したり、キャッシュ無効化のためのクエリパラメータとして使用したり、デプロイ情報を追跡したりする際に役立ちます。

使用例

import { version } from '$app/environment';

// フッターにバージョン情報を表示
<footer>
  アプリバージョン: {version}
</footer>

// キャッシュ無効化のためにバージョンパラメータを追加
const apiUrl = `/api/data?v=${version}`;