Configuration des Assets

Aperçu des options de configuration pour Nette Assets.

assets:
	# chemin de base pour la résolution des chemins relatifs des mappers
	basePath: ...            # (string) par défaut à %wwwDir%

	# URL de base pour la résolution des URL relatives des mappers
	baseUrl: ...             # (string) par défaut à %baseUrl%

	# activer le versioning des assets globalement ?
	versioning: ...           # (bool) par défaut à true

	# définit les mappers d'assets
	mapping: ...             # (array) par défaut au chemin 'assets'

Le basePath définit le répertoire de système de fichiers par défaut pour la résolution des chemins relatifs dans les mappers. Par défaut, il utilise le répertoire web (%wwwDir%).

Le baseUrl définit le préfixe d'URL par défaut pour la résolution des URL relatives dans les mappers. Par défaut, il utilise l'URL racine (%baseUrl%).

L'option versioning contrôle globalement si les paramètres de version sont ajoutés aux URL des assets pour l'invalidation du cache. Les mappers individuels peuvent outrepasser ce paramètre.

Mappers

Les mappers peuvent être configurés de trois manières : notation de chaîne simple, notation de tableau détaillée, ou comme référence à un service.

La manière la plus simple de définir un mapper :

assets:
	mapping:
		default: assets     # Crée un mapper de système de fichiers pour %wwwDir%/assets/
		images: img         # Crée un mapper de système de fichiers pour %wwwDir%/img/
		scripts: js         # Crée un mapper de système de fichiers pour %wwwDir%/js/

Chaque mapper crée un FilesystemMapper qui :

Cherche les fichiers dans %wwwDir%/<path>
Génère des URL comme %baseUrl%/<path>
Hérite du paramètre de versioning global

Pour plus de contrôle, utilisez la notation détaillée :

assets:
	mapping:
		images:
			# répertoire où les fichiers sont stockés
			path: ...                    # (string) optionnel, par défaut à ''

			# préfixe d'URL pour les liens générés
			url: ...                     # (string) optionnel, par défaut à path

			# activer le versioning pour ce mapper ?
			versioning: ...              # (bool) optionnel, hérite du paramètre global

			# ajouter automatiquement l'extension (les extensions) lors de la recherche de fichiers
			extension: ...               # (string|array) optionnel, par défaut à null

Comprendre comment les valeurs de configuration sont résolues :

Résolution de chemin: Les chemins relatifs sont résolus à partir de basePath (ou %wwwDir% si basePath n'est pas défini); Les chemins absolus sont utilisés tels quels
Résolution d'URL: Les URL relatives sont résolues à partir de baseUrl (ou %baseUrl% si baseUrl n'est pas défini); Les URL absolues (avec schéma ou //) sont utilisées telles quelles; Si url n'est pas spécifié, il utilise la valeur de path

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

	mapping:
		# Chemin et URL relatifs
		images:
			path: img                    # Résolu en : /var/www/project/www/img
			url: images                  # Résolu en : https://example.com/assets/images

		# Chemin et URL absolus
		uploads:
			path: /var/shared/uploads    # Utilisé tel quel : /var/shared/uploads
			url: https://cdn.example.com # Utilisé tel quel : https://cdn.example.com

		# Seul le chemin est spécifié
		styles:
			path: css                    # Chemin : /var/www/project/www/css
										 # URL : https://example.com/assets/css

Mappers personnalisés

Pour les mappers personnalisés, référencez ou définissez un service :

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

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

Vite Mapper

Le mapper Vite ne nécessite que l'ajout de type: vite. Voici une liste complète des options de configuration :

assets:
	mapping:
		default:
			# type de mapper (obligatoire pour Vite)
			type: vite                # (string) obligatoire, doit être 'vite'

			# répertoire de sortie de la build Vite
			path: ...                 # (string) optionnel, par défaut à ''

			# préfixe d'URL pour les assets construits
			url: ...                  # (string) optionnel, par défaut à path

			# emplacement du fichier manifest de Vite
			manifest: ...             # (string) optionnel, par défaut à <path>/.vite/manifest.json

			# configuration du serveur de développement Vite
			devServer: ...            # (bool|string) optionnel, par défaut à true

			# versioning pour les fichiers du répertoire public
			versioning: ...           # (bool) optionnel, hérite du paramètre global

			# auto-extension pour les fichiers du répertoire public
			extension: ...            # (string|array) optionnel, par défaut à null

L'option devServer contrôle la manière dont les assets sont chargés pendant le développement :

true (par défaut) – Détecte automatiquement le serveur de développement Vite sur l'hôte et le port actuels. Si le serveur de développement est en cours d'exécution et que votre application est en mode débogage, les assets sont chargés à partir de celui-ci avec le support du rechargement à chaud des modules (HMR). Si le serveur de développement n'est pas en cours d'exécution, les assets sont chargés à partir des fichiers construits dans le répertoire public.
false – Désactive complètement l'intégration du serveur de développement. Les assets sont toujours chargés à partir des fichiers construits.
URL personnalisée (par exemple, https://localhost:5173) – Spécifiez manuellement l'URL du serveur de développement, y compris le protocole et le port. Utile lorsque le serveur de développement s'exécute sur un hôte ou un port différent.

Les options versioning et extension s'appliquent uniquement aux fichiers du répertoire public de Vite qui ne sont pas traités par Vite.

Configuration manuelle

Lorsque vous n'utilisez pas Nette DI, configurez les mappers manuellement :

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

$registry = new Registry;

// Ajoute un mapper de système de fichiers
$registry->addMapper('images', new FilesystemMapper(
	baseUrl: 'https://example.com/img',
	basePath: __DIR__ . '/www/img',
	extensions: ['webp', 'jpg', 'png'],
	versioning: true,
));

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