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

よっしー

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

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

背景
$app/paths
おわりに

背景

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

$app/paths

import { assets, base, resolveRoute } from '$app/paths';

$app/paths モジュールは SvelteKit アプリケーションでパスやルートを扱うための重要なユーティリティを提供します。このモジュールには以下の3つのエクスポートが含まれています：

assets – アプリケーションの静的アセット（画像、スタイルシート、クライアントサイドJavaScriptなど）へのベースパスを提供します。これはビルド時に設定され、アプリケーションがサブディレクトリにデプロイされる場合などに特に重要です。
base – アプリケーションのベースパスを提供します。これはアプリケーションがサブパスにホストされる場合に使用されます。例えば、アプリケーションが https://example.com/myapp/ にデプロイされる場合、base は /myapp になります。
resolveRoute – ルート ID からURLパスを解決するための関数です。これはプログラムによって動的にルートを解決したい場合に便利です。

これらのユーティリティを使用することで、アプリケーションがどのようにデプロイされるかに関係なく、正しいパスを構築できます。これは特に、アプリケーションがルートディレクトリではなくサブディレクトリにホストされる場合に重要です。

使用例

<script>
  import { assets, base, resolveRoute } from '$app/paths';
  
  // アセットへのパスを構築
  const logoPath = `${assets}/images/logo.png`;
  
  // ベースパスを考慮したリンク
  const homeLink = `${base}/`;
  const aboutLink = `${base}/about`;
  
  // ルート ID からパスを解決
  const blogPath = resolveRoute('blog');
  const productPath = resolveRoute('products/[id]', { id: '123' });
</script>

<header>
  <img src={logoPath} alt="ロゴ" />
  <nav>
    <a href={homeLink}>ホーム</a>
    <a href={aboutLink}>会社概要</a>
    <a href={blogPath}>ブログ</a>
    <a href={productPath}>商品 #123</a>
  </nav>
</header>

このモジュールを適切に使用することで、アプリケーションのデプロイ設定が変更されても、すべてのリンクやアセットの参照が正しく機能するようになります。特に、サブディレクトリへのデプロイや CDN の使用など、さまざまなホスティング状況に対応するために重要です。

assets

config.kit.paths.assets に一致する絶対パスです。 config.kit.paths.assets の値が指定されている場合、vite dev または vite preview の実行中は '/_svelte_kit_assets' に置き換えられます。これは、アセットがまだ最終的な URL に配置されていないためです。

let assets:
	| ''
	| `https://${string}`
	| `http://${string}`
	| '/_svelte_kit_assets';

解説

assets は SvelteKit の $app/paths モジュールが提供する定数で、以下のような特徴があります：

アセットパスの取得 – 静的アセット（画像、CSS、クライアント側 JavaScript など）へのパスを取得するために使用します。
絶対パス – assets は常に絶対パスとして提供されます。これは相対パスを使用する場合の混乱を避けるために重要です。
可能な値:
- 空文字列 '' – アセットがアプリケーションと同じ場所にホストされている場合
- https://... または http://... で始まる URL – アセットが CDN など別のドメインでホストされている場合
- '/_svelte_kit_assets' – 開発中またはプレビュー中の一時的な値
設定との関係 – svelte.config.js の kit.paths.assets 設定に基づいています。
開発環境での動作 – 開発時には実際のアセットパスが確定していないため、一時的な値 '/_svelte_kit_assets' が使用されます。

使用例

<script>
  import { assets } from '$app/paths';
  
  // アセットへのパスを構築
  const logoPath = `${assets}/images/logo.png`;
  const stylePath = `${assets}/styles/custom.css`;
  const scriptPath = `${assets}/scripts/utils.js`;
</script>

<header>
  <!-- アセットパスを使用して画像を参照 -->
  <img src="{logoPath}" alt="会社ロゴ" />
  
  <!-- 外部スタイルシートの読み込み -->
  <link rel="stylesheet" href="{stylePath}">
  
  <!-- 外部 JavaScript の読み込み -->
  <script src="{scriptPath}"></script>
</header>

このように assets を使用することで、アプリケーションのデプロイ設定が変更されても（例えば、CDN を使用するようになった場合）、すべてのアセット参照が自動的に正しいパスを指すようになります。特に以下のシナリオで重要です：

CDN の使用 – アセットが別のドメインにホストされる場合
サブディレクトリへのデプロイ – アプリがルートではなくサブディレクトリにホストされる場合
開発と本番環境の違い – 開発環境と本番環境でアセットの場所が異なる場合

assets を使用すると、これらの違いを気にせずに一貫したコードを書くことができます。

base

config.kit.paths.base に一致する文字列です。使用例: <a href="{base}/your-page">リンク</a>

let base: '' | `/${string}`;

解説

base は SvelteKit の $app/paths モジュールが提供する定数で、以下のような特徴があります：

ベースパスの取得 – アプリケーションのベースパス（基準となるパス）を取得するために使用します。
可能な値:
- 空文字列 '' – アプリケーションがドメインのルートにホストされている場合
- / で始まる文字列 – アプリケーションがサブディレクトリにホストされている場合（例: /myapp）
設定との関係 – svelte.config.js の kit.paths.base 設定と直接連動しています。
用途 – すべての内部リンクや API リクエストの前に付加することで、アプリケーションがサブディレクトリにデプロイされても正しく機能するようにします。

使用例

<script>
  import { base } from '$app/paths';
  
  // アプリケーション内のページへの完全なパスを構築
  const homeLink = `${base}/`;
  const aboutLink = `${base}/about`;
  const contactLink = `${base}/contact`;
  
  // API エンドポイントへのパスも同様に構築
  const apiUrl = `${base}/api/data`;
</script>

<nav>
  <ul>
    <li><a href="{homeLink}">ホーム</a></li>
    <li><a href="{aboutLink}">会社概要</a></li>
    <li><a href="{contactLink}">お問い合わせ</a></li>
  </ul>
</nav>

<button on:click={() => fetch(apiUrl).then(r => r.json())}>
  データを取得
</button>

base を使用することで得られる主な利点：

デプロイの柔軟性 – アプリケーションをドメインのルートまたは任意のサブディレクトリにデプロイできます。svelte.config.js の設定を変更するだけで、すべてのリンクが自動的に正しいパスを指すようになります。
移植性の向上 – 同じコードベースを異なる環境（開発、テスト、本番など）で異なるベースパスでデプロイできます。
リンクの一貫性 – すべてのリンクが確実に正しいベースパスを使用するため、「リンク切れ」のリスクが軽減されます。

特に、以下のような状況で base の使用が重要になります：

サブディレクトリへのデプロイ（例: https://example.com/myapp/）
リバースプロキシの背後でのホスティング
同じコードベースを複数の異なるパスでデプロイする場合

base を一貫して使用することで、これらのデプロイシナリオの変更に対応しやすくなります。

resolveRoute

パラメータを使ってルート ID からパス名を解決します。

import { resolveRoute } from '$app/paths';

resolveRoute(
	`/blog/[slug]/[...somethingElse]`,
	{
		slug: 'hello-world',
		somethingElse: 'something/else'
	}
); // `/blog/hello-world/something/else`

function resolveRoute(
	id: string,
	params: Record<string, string | undefined>
): string;

解説

resolveRoute は SvelteKit の $app/paths モジュールが提供する関数で、以下のような特徴があります：

ルート解決 – パラメータを使ってルート ID（パターン）からパス名（実際の URL パス）を解決します。
引数:
- id: ルート ID（パターン）。[パラメータ名] または [...パラメータ名] の形式のプレースホルダーを含むことができます。
- params: プレースホルダーを埋めるためのパラメータを含むオブジェクト。
プレースホルダーの種類:
- [param] – 単一のパスセグメントを表すプレースホルダー
- [...param] – 複数のパスセグメントを含むことができるレスト（rest）パラメータ
戻り値 – 解決されたパス名（文字列）

使用例

<script>
  import { resolveRoute } from '$app/paths';
  import { base } from '$app/paths';
  
  // 基本的なルート解決
  const aboutPath = resolveRoute('/about', {});
  
  // パラメータを含むルート
  const productPath = resolveRoute('/products/[id]', { id: '123' });
  
  // 複数のパラメータ
  const blogPostPath = resolveRoute('/blog/[category]/[slug]', {
    category: 'tech',
    slug: 'svelte-kit-introduction'
  });
  
  // レストパラメータ
  const docsPath = resolveRoute('/docs/[...path]', {
    path: 'api/navigation/goto'
  });
  
  // base パスと組み合わせて完全な URL を構築
  const fullProductPath = `${base}${productPath}`;
</script>

<nav>
  <ul>
    <li><a href="{base}{aboutPath}">会社概要</a></li>
    <li><a href="{base}{productPath}">商品 #123</a></li>
    <li><a href="{base}{blogPostPath}">ブログ記事</a></li>
    <li><a href="{base}{docsPath}">ドキュメント</a></li>
  </ul>
</nav>

<script>
  // プログラムによるナビゲーションでも使用可能
  import { goto } from '$app/navigation';
  
  function navigateToProduct(id) {
    const path = resolveRoute('/products/[id]', { id });
    goto(`${base}${path}`);
  }
  
  // 動的なリンク生成
  function generateCategoryLinks(categories) {
    return categories.map(category => {
      const path = resolveRoute('/categories/[name]', { name: category.slug });
      return {
        href: `${base}${path}`,
        label: category.name
      };
    });
  }
</script>

resolveRoute の主な利点：