Konfiguration von Assets

Übersicht der Konfigurationsoptionen für Nette Assets.

assets:
	# Basispfad zum Auflösen relativer Pfade der Mapper
	basePath: ...            # (string) Standardwert ist %wwwDir%

	# Basis-URL zum Auflösen relativer URLs der Mapper
	baseUrl: ...             # (string) Standardwert ist %baseUrl%

	# Versionierung der Assets global aktivieren?
	versioning: ...           # (bool) Standardwert ist true

	# definiert die Asset-Mapper
	mapping: ...             # (array) Standardwert ist der Pfad 'assets'

basePath setzt das Standardverzeichnis im Dateisystem zum Auflösen relativer Pfade in den Mappern. Standardmäßig wird das Web-Verzeichnis verwendet (%wwwDir%).

baseUrl setzt das Standard-URL-Präfix zum Auflösen relativer URLs in den Mappern. Standardmäßig wird die Wurzel-URL verwendet (%baseUrl%).

Die Option versioning steuert global, ob den URLs der Assets Versionsparameter fürs Cache Busting angehängt werden. Einzelne Mapper können diese Einstellung überschreiben.

Mapper

Mapper lassen sich auf drei Arten konfigurieren: in einfacher String-Schreibweise, in ausführlicher Array-Schreibweise oder als Service (mit der Entity-Schreibweise ClassName(...) bzw. @serviceName()).

Der einfachste Weg, einen Mapper zu definieren:

assets:
	mapping:
		default: assets     # erzeugt einen Filesystem-Mapper für %wwwDir%/assets/
		images: img         # erzeugt einen Filesystem-Mapper für %wwwDir%/img/
		scripts: js         # erzeugt einen Filesystem-Mapper für %wwwDir%/js/

Jeder Mapper erzeugt einen FilesystemMapper, der:

• Dateien in %wwwDir%/<path> sucht
• URLs der Form %baseUrl%/<path> erzeugt
• die globale Einstellung zur Versionierung erbt

Für mehr Kontrolle verwenden Sie die ausführliche Schreibweise:

assets:
	mapping:
		images:
			# Verzeichnis, in dem die Dateien liegen
			path: ...                    # (string) optional, Standardwert ist der Basispfad (basePath)

			# URL-Präfix für die erzeugten Links
			url: ...                     # (string) optional, Standardwert ist path

			# Versionierung für diesen Mapper aktivieren?
			versioning: ...              # (bool) optional, erbt die globale Einstellung

			# Endung(en) beim Suchen von Dateien automatisch ergänzen
			extension: ...               # (string|array) optional, Standardwert ist null

So werden die Konfigurationswerte aufgelöst:

Auflösung der Pfade

Relative Pfade werden von basePath aus aufgelöst (oder von %wwwDir%, wenn basePath nicht gesetzt ist)

Absolute Pfade werden unverändert verwendet

Auflösung der URLs

Relative URLs werden von baseUrl aus aufgelöst (oder von %baseUrl%, wenn baseUrl nicht gesetzt ist)

Absolute URLs (mit Schema oder //) werden unverändert verwendet (eine //-URL erhält ihr Schema aus baseUrl)

Ist url nicht angegeben, wird der Wert von path verwendet

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

	mapping:
		# relativer Pfad und relative URL
		images:
			path: img                    # aufgelöst zu: /var/www/project/www/img
			url: images                  # aufgelöst zu: https://example.com/assets/images

		# absoluter Pfad und absolute URL
		uploads:
			path: /var/shared/uploads    # unverändert verwendet: /var/shared/uploads
			url: https://cdn.example.com # unverändert verwendet: https://cdn.example.com

		# nur der Pfad angegeben
		styles:
			path: css                    # Pfad: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Eigene Mapper

Bei eigenen Mappern verweisen Sie mit @serviceName auf einen bestehenden Service oder definieren ihn direkt über ClassName(arguments) bzw. einen bloßen Klassennamen:

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

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

Vite-Mapper

Beim Vite-Mapper müssen Sie nur type: vite ergänzen. Das ist die vollständige Liste der Konfigurationsoptionen:

assets:
	mapping:
		default:
			# Typ des Mappers (bei Vite erforderlich)
			type: vite                # (string) erforderlich, muss 'vite' sein

			# Ausgabeverzeichnis des Vite-Builds
			path: ...                 # (string) optional, Standardwert ist der Basispfad (basePath)

			# URL-Präfix für die gebauten Assets
			url: ...                  # (string) optional, Standardwert ist path

			# Ort der Manifest-Datei von Vite
			manifest: ...             # (string) optional, relativ zu path, Standardwert ist <path>/.vite/manifest.json

			# Konfiguration des Vite-Dev-Servers
			devServer: ...            # (bool|string) optional, Standardwert ist true

			# Versionierung für Dateien im Public-Verzeichnis
			versioning: ...           # (bool) optional, erbt die globale Einstellung

			# automatische Endung für Dateien im Public-Verzeichnis
			extension: ...            # (string|array) optional, Standardwert ist null

Die Option devServer steuert, wie die Assets während der Entwicklung geladen werden:

• true (Standard) – Erkennt automatisch einen laufenden Vite-Dev-Server (über die Datei .vite/nette.json, die das Nette-Vite-Plugin im Build-Verzeichnis anlegt). Läuft der Dev-Server und ist Ihre Anwendung im Debug-Modus, werden die Assets von ihm geladen, samt Unterstützung für Hot Module Replacement. Läuft der Dev-Server nicht, werden die Assets aus den gebauten Dateien im öffentlichen Verzeichnis geladen.
• false – Schaltet die Integration des Dev-Servers vollständig ab. Die Assets werden immer aus den gebauten Dateien geladen.
• Eigene URL (z. B. https://localhost:5173) – Gibt die URL des Dev-Servers samt Protokoll und Port von Hand an. Nützlich, wenn der Dev-Server auf einem anderen Host oder Port läuft. Wie die automatische Erkennung gilt sie nur im Debug-Modus; in der Produktion werden immer die gebauten Dateien verwendet.

Die Optionen versioning und extension gelten nur für Dateien im Public-Verzeichnis von Vite, die von Vite nicht verarbeitet werden.

Manuelle Konfiguration

Wenn Sie Nette DI nicht verwenden, konfigurieren Sie die Mapper von Hand:

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

$registry = new Registry;

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

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

Jeden registrierten Mapper können Sie außerdem mit der Methode getMapper() über seinen Namen holen:

$mapper = $registry->getMapper('images');   // gibt den registrierten Mapper zurück
$default = $registry->getMapper();           // gibt den Mapper 'default' zurück