Konfigurace Assets

Přehled možností konfigurace pro Nette Assets.

assets:
	# základní cesta pro řešení relativních cest mapperů
	basePath: ...            # (string) výchozí hodnota je %wwwDir%

	# základní URL pro řešení relativních URL mapperů
	baseUrl: ...             # (string) výchozí hodnota je %baseUrl%

	# povolit globální verzování assetů?
	versioning: ...           # (bool) výchozí hodnota je true

	# definuje mappery assetů
	mapping: ...             # (array) výchozí hodnota je cesta 'assets'

basePath nastavuje výchozí adresář souborového systému pro řešení relativních cest v mapperech. Ve výchozím nastavení používá webový adresář (%wwwDir%).

baseUrl nastavuje výchozí URL prefix pro řešení relativních URL v mapperech. Ve výchozím nastavení používá kořenovou URL (%baseUrl%).

Možnost versioning globálně řídí, zda jsou k URL assetů přidávány parametry verzí pro zrušení cache. Jednotlivé mappery mohou toto nastavení přepsat.

Mappery

Mappery lze konfigurovat třemi způsoby: jednoduchou řetězcovou notací, detailní notací pole nebo jako odkaz na službu.

Nejjednodušší způsob, jak definovat mapper:

assets:
	mapping:
		default: assets     # Vytvoří filesystem mapper pro %wwwDir%/assets/
		images: img         # Vytvoří filesystem mapper pro %wwwDir%/img/
		scripts: js         # Vytvoří filesystem mapper pro %wwwDir%/js/

Každý mapper vytvoří FilesystemMapper, který:

• Hledá soubory v %wwwDir%/<path>
• Generuje URL jako %baseUrl%/<path>
• Dědí globální nastavení verzování

Pro větší kontrolu použijte detailní notaci:

assets:
	mapping:
		images:
			# adresář, kde jsou soubory uloženy
			path: ...                    # (string) volitelné, výchozí hodnota je ''

			# URL prefix pro generované odkazy
			url: ...                     # (string) volitelné, výchozí hodnota je cesta

			# povolit verzování pro tento mapper?
			versioning: ...              # (bool) volitelné, dědí globální nastavení

			# automaticky přidat příponu(y) při hledání souborů
			extension: ...               # (string|array) volitelné, výchozí hodnota je null

Pochopení, jak se řeší konfigurační hodnoty:

Řešení cest

Relativní cesty jsou řešeny z basePath (nebo %wwwDir%, pokud basePath není nastaveno)

Absolutní cesty jsou použity tak, jak jsou

Řešení URL

Relativní URL jsou řešeny z baseUrl (nebo %baseUrl%, pokud baseUrl není nastaveno)

Absolutní URL (se schématem nebo //) jsou použity tak, jak jsou

Pokud url není specifikováno, použije hodnotu path

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

	mapping:
		# Relativní cesta a URL
		images:
			path: img                    # Vyřešeno na: /var/www/project/www/img
			url: images                  # Vyřešeno na: https://example.com/assets/images

		# Absolutní cesta a URL
		uploads:
			path: /var/shared/uploads    # Použito tak, jak je: /var/shared/uploads
			url: https://cdn.example.com # Použito tak, jak je: https://cdn.example.com

		# Pouze cesta specifikována
		styles:
			path: css                    # Cesta: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Vlastní mappery

Pro vlastní mappery odkazujte nebo definujte službu:

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

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

Vite Mapper

Vite mapper vyžaduje pouze přidání type: vite. Zde je kompletní seznam konfiguračních možností:

assets:
	mapping:
		default:
			# typ mapperu (vyžadováno pro Vite)
			type: vite                # (string) vyžadováno, musí být 'vite'

			# výstupní adresář Vite buildu
			path: ...                 # (string) volitelné, výchozí hodnota je ''

			# URL prefix pro sestavené assety
			url: ...                  # (string) volitelné, výchozí hodnota je cesta

			# umístění souboru manifestu Vite
			manifest: ...             # (string) volitelné, výchozí hodnota je <path>/.vite/manifest.json

			# konfigurace Vite dev serveru
			devServer: ...            # (bool|string) volitelné, výchozí hodnota je true

			# verzování souborů ve veřejném adresáři
			versioning: ...           # (bool) volitelné, dědí globální nastavení

			# automatická přípona pro soubory ve veřejném adresáři
			extension: ...            # (string|array) volitelné, výchozí hodnota je null

Možnost devServer řídí, jak se assety načítají během vývoje:

• true (výchozí) – Automaticky detekuje Vite dev server na aktuálním hostiteli a portu. Pokud je dev server spuštěn a vaše aplikace je v debug režimu, assety se z něj načítají s podporou hot module replacement. Pokud dev server neběží, assety se načítají ze sestavených souborů ve veřejném adresáři.
• false – Zcela zakáže integraci dev serveru. Assety se vždy načítají ze sestavených souborů.
• Vlastní URL (např. https://localhost:5173) – Ručně zadejte URL dev serveru včetně protokolu a portu. Užitečné, když dev server běží na jiném hostiteli nebo portu.

Možnosti versioning a extension se vztahují pouze na soubory ve veřejném adresáři Vite, které nejsou zpracovány Vite.

Ruční konfigurace

Pokud nepoužíváte Nette DI, nakonfigurujte mappery ručně:

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

$registry = new Registry;

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

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