Конфігурація активів

Огляд опцій конфігурації для Nette Assets.

assets:
	# base path for resolving relative mapper paths
	basePath: ...            # (string) defaults to %wwwDir%

	# base URL for resolving relative mapper URLs
	baseUrl: ...             # (string) defaults to %baseUrl%

	# enable asset versioning globally?
	versioning: ...           # (bool) defaults to true

	# defines asset mappers
	mapping: ...             # (array) defaults to path 'assets'

basePath встановлює типовий каталог файлової системи для розв'язання відносних шляхів у маперах. За замовчуванням він використовує веб-каталог (%wwwDir%).

baseUrl встановлює типовий префікс URL для розв'язання відносних URL у маперах. За замовчуванням він використовує кореневий URL (%baseUrl%).

Опція versioning глобально контролює, чи додаються параметри версії до URL-адрес активів для обходу кешу. Окремі мапери можуть перевизначати це налаштування.

Мапери

Мапери можуть бути налаштовані трьома способами: проста рядкова нотація, детальна масивна нотація або як посилання на сервіс.

Найпростіший спосіб визначити мапер:

assets:
	mapping:
		default: assets     # Creates filesystem mapper for %wwwDir%/assets/
		images: img         # Creates filesystem mapper for %wwwDir%/img/
		scripts: js         # Creates filesystem mapper for %wwwDir%/js/

Кожен мапер створює FilesystemMapper, який:

• Шукає файли в %wwwDir%/<path>
• Генерує URL-адреси, такі як %baseUrl%/<path>
• Успадковує глобальні налаштування версіонування

Для більшого контролю використовуйте детальну нотацію:

assets:
	mapping:
		images:
			# directory where files are stored
			path: ...                    # (string) optional, defaults to ''

			# URL prefix for generated links
			url: ...                     # (string) optional, defaults to path

			# enable versioning for this mapper?
			versioning: ...              # (bool) optional, inherits global setting

			# auto-add extension(s) when searching for files
			extension: ...               # (string|array) optional, defaults to null

Розуміння того, як розв'язуються значення конфігурації:

Розв'язання шляхів

Відносні шляхи розв'язуються з basePath (або %wwwDir%, якщо basePath не встановлено)

Абсолютні шляхи використовуються як є

Розв'язання URL

Відносні URL-адреси розв'язуються з baseUrl (або %baseUrl%, якщо baseUrl не встановлено)

Абсолютні URL-адреси (зі схемою або //) використовуються як є

Якщо url не вказано, використовується значення path

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

	mapping:
		# Relative path and URL
		images:
			path: img                    # Resolved to: /var/www/project/www/img
			url: images                  # Resolved to: https://example.com/assets/images

		# Absolute path and URL
		uploads:
			path: /var/shared/uploads    # Used as-is: /var/shared/uploads
			url: https://cdn.example.com # Used as-is: https://cdn.example.com

		# Only path specified
		styles:
			path: css                    # Path: /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 Mapper

Мапер Vite вимагає лише додати type: vite. Це повний список опцій конфігурації:

assets:
	mapping:
		default:
			# mapper type (required for Vite)
			type: vite                # (string) required, must be 'vite'

			# Vite build output directory
			path: ...                 # (string) optional, defaults to ''

			# URL prefix for built assets
			url: ...                  # (string) optional, defaults to path

			# location of Vite manifest file
			manifest: ...             # (string) optional, defaults to <path>/.vite/manifest.json

			# Vite dev server configuration
			devServer: ...            # (bool|string) optional, defaults to true

			# versioning for public directory files
			versioning: ...           # (bool) optional, inherits global setting

			# auto-extension for public directory files
			extension: ...            # (string|array) optional, defaults to null

Опція devServer контролює, як активи завантажуються під час розробки:

• true (за замовчуванням) – Автоматично виявляє dev-сервер Vite на поточному хості та порту. Якщо dev-сервер запущений і ваш додаток знаходиться в режимі налагодження, активи завантажуються з нього з підтримкою гарячої заміни модулів. Якщо dev-сервер не запущений, активи завантажуються з збудованих файлів у публічному каталозі.
• false – Повністю вимикає інтеграцію dev-сервера. Активи завжди завантажуються з збудованих файлів.
• Користувацький URL (наприклад, https://localhost:5173) – Вручну вказує URL dev-сервера, включаючи протокол та порт. Корисно, коли dev-сервер працює на іншому хості або порту.

Опції versioning та extension застосовуються лише до файлів у публічному каталозі Vite, які не обробляються Vite.

Ручна конфігурація

Якщо не використовуєте Nette DI, налаштуйте мапери вручну:

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

$registry = new Registry;

// Add filesystem mapper
$registry->addMapper('images', new FilesystemMapper(
	baseUrl: 'https://example.com/img',
	basePath: __DIR__ . '/www/img',
	extensions: ['webp', 'jpg', 'png'],
	versioning: true,
));

// Add Vite mapper
$registry->addMapper('app', new ViteMapper(
	baseUrl: '/build',
	basePath: __DIR__ . '/www/build',
	manifestPath: __DIR__ . '/www/build/.vite/manifest.json',
	devServer: 'https://localhost:5173',
));