アセット設定

Nette Assetsの設定オプションの概要。

assets:
	# 相対マッパーパスを解決するためのベースパス
	basePath: ...            # (string) デフォルトは %wwwDir%

	# 相対マッパーURLを解決するためのベースURL
	baseUrl: ...             # (string) デフォルトは %baseUrl%

	# アセットのバージョニングをグローバルに有効にするか？
	versioning: ...           # (bool) デフォルトは true

	# アセットマッパーを定義
	mapping: ...             # (array) デフォルトはパス 'assets'

basePathは、マッパー内の相対パスを解決するためのデフォルトのファイルシステムディレクトリを設定します。デフォルトでは、ウェブディレクトリ（%wwwDir%）を使用します。

baseUrlは、マッパー内の相対URLを解決するためのデフォルトのURLプレフィックスを設定します。デフォルトでは、ルートURL（%baseUrl%）を使用します。

versioningオプションは、キャッシュバストのためにアセットURLにバージョンパラメータを追加するかどうかをグローバルに制御します。個々のマッパーはこの設定を上書きできます。

マッパー

マッパーは、単純な文字列表記、詳細な配列表記、またはサービスへの参照の3つの方法で設定できます。

マッパーを定義する最も簡単な方法：

assets:
	mapping:
		default: assets     # %wwwDir%/assets/ のファイルシステムマッパーを作成
		images: img         # %wwwDir%/img/ のファイルシステムマッパーを作成
		scripts: js         # %wwwDir%/js/ のファイルシステムマッパーを作成

各マッパーはFilesystemMapperを作成し、次のことを行います。

%wwwDir%/<path>内のファイルを検索します
%baseUrl%/<path>のようなURLを生成します
グローバルなバージョニング設定を継承します

より詳細な制御が必要な場合は、詳細な表記を使用します。

assets:
	mapping:
		images:
			# ファイルが保存されているディレクトリ
			path: ...                    # (string) オプション、デフォルトは ''

			# 生成されるリンクのURLプレフィックス
			url: ...                     # (string) オプション、デフォルトは path

			# このマッパーのバージョニングを有効にするか？
			versioning: ...              # (bool) オプション、グローバル設定を継承

			# ファイルを検索する際に拡張子を自動追加するか？
			extension: ...               # (string|array) オプション、デフォルトは null

設定値がどのように解決されるかを理解する：

パス解決：
- 相対パスはbasePath（またはbasePathが設定されていない場合は%wwwDir%）から解決されます
- 絶対パスはそのまま使用されます

URL解決：
- 相対URLはbaseUrl（またはbaseUrlが設定されていない場合は%baseUrl%）から解決されます
- 絶対URL（スキームまたは//を含む）はそのまま使用されます
- urlが指定されていない場合、pathの値が使用されます

assets:
	basePath: /var/www/project/www
	baseUrl: https://example.com/assets

	mapping:
		# 相対パスとURL
		images:
			path: img                    # 解決済み: /var/www/project/www/img
			url: images                  # 解決済み: https://example.com/assets/images

		# 絶対パスとURL
		uploads:
			path: /var/shared/uploads    # そのまま使用: /var/shared/uploads
			url: https://cdn.example.com # そのまま使用: https://cdn.example.com

		# パスのみ指定
		styles:
			path: css                    # パス: /var/www/project/www/css
										 # URL: https://example.com/assets/css

カスタムマッパー

カスタムマッパーの場合は、サービスを参照するか定義します。

services:
	s3mapper: App\Assets\S3Mapper(%s3.bucket%)

assets:
	mapping:
		cloud: @s3mapper
		database: App\Assets\DatabaseMapper(@database.connection)

Viteマッパー

Viteマッパーはtype: viteを追加するだけで済みます。以下は設定オプションの完全なリストです。

assets:
	mapping:
		default:
			# マッパータイプ (Viteに必須)
			type: vite                # (string) 必須、'vite'でなければならない

			# Viteビルド出力ディレクトリ
			path: ...                 # (string) オプション、デフォルトは ''

			# ビルドされたアセットのURLプレフィックス
			url: ...                  # (string) オプション、デフォルトは path

			# Viteマニフェストファイルの場所
			manifest: ...             # (string) オプション、デフォルトは <path>/.vite/manifest.json

			# Vite開発サーバー設定
			devServer: ...            # (bool|string) オプション、デフォルトは true

			# publicディレクトリファイルのバージョニング
			versioning: ...           # (bool) オプション、グローバル設定を継承

			# publicディレクトリファイルの自動拡張子
			extension: ...            # (string|array) オプション、デフォルトは null

devServerオプションは、開発中にアセットがどのようにロードされるかを制御します。

true（デフォルト） – 現在のホストとポートでVite開発サーバーを自動的に検出します。開発サーバーが実行中でアプリケーションがデバッグモードの場合、アセットはホットモジュールリプレイスメント（HMR）をサポートしてそこからロードされます。開発サーバーが実行されていない場合、アセットはpublicディレクトリ内のビルド済みファイルからロードされます。
false – 開発サーバーの連携を完全に無効にします。アセットは常にビルド済みファイルからロードされます。
カスタムURL（例: https://localhost:5173） – プロトコルとポートを含む開発サーバーのURLを手動で指定します。開発サーバーが異なるホストまたはポートで実行されている場合に便利です。

versioningとextensionオプションは、Viteによって処理されないViteのpublicディレクトリ内のファイルにのみ適用されます。

手動設定

Nette DIを使用しない場合、マッパーを手動で設定します。

use Nette\Assets\Registry;
use Nette\Assets\FilesystemMapper;
use Nette\Assets\ViteMapper;

$registry = new Registry;

// ファイルシステムマッパーを追加
$registry->addMapper('images', new FilesystemMapper(
	baseUrl: 'https://example.com/img',
	basePath: __DIR__ . '/www/img',
	extensions: ['webp', 'jpg', 'png'],
	versioning: true,
));

// Viteマッパーを追加
$registry->addMapper('app', new ViteMapper(
	baseUrl: '/build',
	basePath: __DIR__ . '/www/build',
	manifestPath: __DIR__ . '/www/build/.vite/manifest.json',
	devServer: 'https://localhost:5173',
));