Konfigurácia Assets

Prehľad možností konfigurácie pre Nette Assets.

assets:
	# základná cesta pre rozlíšenie relatívnych ciest mapperov
	basePath: ...            # (string) predvolené na %wwwDir%

	# základná URL pre rozlíšenie relatívnych URL mapperov
	baseUrl: ...             # (string) predvolené na %baseUrl%

	# povoliť globálne verzovanie assetov?
	versioning: ...           # (bool) predvolené na true

	# definuje asset mappery
	mapping: ...             # (array) predvolené na cestu 'assets'

basePath nastavuje predvolený adresár súborového systému pre rozlíšenie relatívnych ciest v mapperoch. Východiskovo používa webový adresár (%wwwDir%).

baseUrl nastavuje predvolený URL prefix pre rozlíšenie relatívnych URL v mapperoch. Východiskovo používa koreňovú URL (%baseUrl%).

Možnosť versioning globálne riadi, či sa do URL adries assetov pridávajú parametre verzie pre cache busting. Jednotlivé mappery môžu toto nastavenie prepísať.

Mappery

Mappery môžu byť konfigurované tromi spôsobmi: jednoduchou reťazcovou notáciou, detailnou notáciou poľa alebo ako odkaz na službu.

Najjednoduchší spôsob definovania mappera:

assets:
	mapping:
		default: assets     # Vytvorí filesystem mapper pre %wwwDir%/assets/
		images: img         # Vytvorí filesystem mapper pre %wwwDir%/img/
		scripts: js         # Vytvorí filesystem mapper pre %wwwDir%/js/

Každý mapper vytvorí FilesystemMapper, ktorý:

• Hľadá súbory v %wwwDir%/<path>
• Generuje URL adresy ako %baseUrl%/<path>
• Dedí globálne nastavenie verzovania

Pre väčšiu kontrolu použite detailnú notáciu:

assets:
	mapping:
		images:
			# adresár, kde sú súbory uložené
			path: ...                    # (string) voliteľné, predvolené na ''

			# URL prefix pre generované odkazy
			url: ...                     # (string) voliteľné, predvolené na path

			# povoliť verzovanie pre tento mapper?
			versioning: ...              # (bool) voliteľné, dedí globálne nastavenie

			# automaticky pridať príponu(y) pri hľadaní súborov
			extension: ...               # (string|array) voliteľné, predvolené na null

Pochopenie, ako sa riešia konfiguračné hodnoty:

Riešenie ciest

Relatívne cesty sa riešia z basePath (alebo %wwwDir%, ak basePath nie je nastavená)

Absolútne cesty sa používajú tak, ako sú

Riešenie URL

Relatívne URL sa riešia z baseUrl (alebo %baseUrl%, ak baseUrl nie je nastavená)

Absolútne URL (so schémou alebo //) sa používajú tak, ako sú

Ak url nie je špecifikovaná, použije sa hodnota path

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

	mapping:
		# Relatívna cesta a URL
		images:
			path: img                    # Rozlíšené na: /var/www/project/www/img
			url: images                  # Rozlíšené na: https://example.com/assets/images

		# Absolútna cesta a URL
		uploads:
			path: /var/shared/uploads    # Použité tak, ako je: /var/shared/uploads
			url: https://cdn.example.com # Použité tak, ako je: https://cdn.example.com

		# Špecifikovaná len cesta
		styles:
			path: css                    # Cesta: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Vlastné Mappery

Pre vlastné mappery, odkážte alebo 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 iba pridanie type: vite. Toto je kompletný zoznam konfiguračných možností:

assets:
	mapping:
		default:
			# typ mappera (povinný pre Vite)
			type: vite                # (string) povinné, musí byť 'vite'

			# výstupný adresár Vite buildu
			path: ...                 # (string) voliteľné, predvolené na ''

			# URL prefix pre vybudované assets
			url: ...                  # (string) voliteľné, predvolené na path

			# umiestnenie súboru Vite manifestu
			manifest: ...             # (string) voliteľné, predvolené na <path>/.vite/manifest.json

			# konfigurácia dev servera Vite
			devServer: ...            # (bool|string) voliteľné, predvolené na true

			# verzovanie pre súbory vo verejnom adresári
			versioning: ...           # (bool) voliteľné, dedí globálne nastavenie

			# auto-prípona pre súbory vo verejnom adresári
			extension: ...            # (string|array) voliteľné, predvolené na null

Možnosť devServer riadi, ako sa assets načítavajú počas vývoja:

• true (predvolené) – Automaticky detekuje Vite dev server na aktuálnom hostiteľovi a porte. Ak dev server beží a vaša aplikácia je v režime ladenia, assets sa z neho načítavajú s podporou hot module replacement. Ak dev server nebeží, assets sa načítavajú z vybudovaných súborov vo verejnom adresári.
• false – Úplne zakáže integráciu dev servera. Assets sa vždy načítavajú z vybudovaných súborov.
• Vlastná URL (napr. https://localhost:5173) – Manuálne špecifikujte URL dev servera vrátane protokolu a portu. Užitočné, keď dev server beží na inom hostiteľovi alebo porte.

Možnosti versioning a extension sa vzťahujú iba na súbory vo verejnom adresári Vite, ktoré nie sú spracované Vite.

Manuálna konfigurácia

Ak nepoužívate Nette DI, nakonfigurujte mappery manuálne:

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

$registry = new Registry;

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

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