Assets の設定

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 とおりに設定できます。単純な文字列の書き方、詳しい配列の書き方、そしてサービスとして（エンティティの書き方 ClassName(...) か @serviceName() を使います）です。

マッパーを定めるいちばん単純な方法です。

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) 省略でき、既定は基本のパス（basePath）

			# 作られるリンクの URL の接頭辞
			url: ...                     # (string) 省略でき、既定は path

			# このマッパーでバージョン付けを有効にしますか
			versioning: ...              # (bool) 省略でき、全体の設定を受け継ぎます

			# ファイルを探すときに拡張子を自動的に足します
			extension: ...               # (string|array) 省略でき、既定は null

設定の値がどう解決されるかを見ていきます。

パスの解決
相対パスは basePath から解決されます（basePath が設定されていなければ %wwwDir% から）
絶対パスはそのまま使われます
URL の解決
相対 URL は baseUrl から解決されます（baseUrl が設定されていなければ %baseUrl% から）
絶対 URL（スキーム付き、または // で始まるもの）はそのまま使われます（// の URL はスキームを baseUrl から得ます）
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

		# path だけを指定した場合
		styles:
			path: css                    # パス: /var/www/project/www/css
										 # URL: https://example.com/assets/css

独自のマッパー

独自のマッパーには、@serviceName で既存のサービスを指すか、ClassName(arguments) か裸のクラス名で直接定めます。

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) 省略でき、既定は基本のパス（basePath）

			# ビルドされたアセットの URL の接頭辞
			url: ...                  # (string) 省略でき、既定は path

			# Vite のマニフェストのファイルの場所
			manifest: ...             # (string) 省略でき、path からの相対。既定は <path>/.vite/manifest.json

			# Vite の開発サーバーの設定
			devServer: ...            # (bool|string) 省略でき、既定は true

			# public のディレクトリのファイルのバージョン付け
			versioning: ...           # (bool) 省略でき、全体の設定を受け継ぎます

			# public のディレクトリのファイルの自動の拡張子
			extension: ...            # (string|array) 省略でき、既定は null

devServer のオプションは、開発中にアセットをどう読み込むかを決めます。

  • true（既定） – 動いている Vite の開発サーバーを自動的に見つけます（Nette の Vite のプラグインがビルドのディレクトリに作る .vite/nette.json ファイルを通してです）。開発サーバーが動いていてアプリケーションがデバッグモードなら、アセットはそこから、ホットモジュールリプレースメントに対応した形で読み込まれます。開発サーバーが動いていなければ、アセットは public のディレクトリのビルドされたファイルから読み込まれます。
  • false – 開発サーバーとの組み合わせを完全に切ります。アセットはいつもビルドされたファイルから読み込まれます。
  • 独自の URL（たとえば https://localhost:5173） – 開発サーバーの URL を、プロトコルとポートも含めて手で指定します。開発サーバーが別のホストやポートで動いているときに便利です。自動の判別と同じく、デバッグモードでだけ効き、本番ではいつもビルドされたファイルが使われます。

versioning と extension のオプションは、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',
));

登録されたどのマッパーも、getMapper() メソッドで名前から取り出せます。

$mapper = $registry->getMapper('images');   // 登録されたマッパーを返します
$default = $registry->getMapper();           // 'default' のマッパーを返します
  1. ドキュメンテーション
  2. Nette Assets
  3. Assets の設定
バージョン: 1.x