Configuración de Assets

Resumen de las opciones de configuración para Nette Assets.

assets:
	# ruta base para resolver rutas relativas del mapper
	basePath: ...            # (string) por defecto %wwwDir%

	# URL base para resolver URLs relativas del mapper
	baseUrl: ...             # (string) por defecto %baseUrl%

	# ¿habilitar el versionado de assets globalmente?
	versioning: ...           # (bool) por defecto true

	# define los mappers de assets
	mapping: ...             # (array) por defecto la ruta 'assets'

basePath establece el directorio del sistema de archivos predeterminado para resolver rutas relativas en los mappers. Por defecto, usa el directorio web (%wwwDir%).

baseUrl establece el prefijo de URL predeterminado para resolver URLs relativas en los mappers. Por defecto, usa la URL raíz (%baseUrl%).

La opción versioning controla globalmente si se añaden parámetros de versión a las URLs de los assets para la eliminación de caché. Los mappers individuales pueden anular esta configuración.

Mappers

Los mappers se pueden configurar de tres maneras: notación de cadena simple, notación de array detallada o como referencia a un servicio.

La forma más sencilla de definir un mapper:

assets:
	mapping:
		default: assets     # Crea un mapper de sistema de archivos para %wwwDir%/assets/
		images: img         # Crea un mapper de sistema de archivos para %wwwDir%/img/
		scripts: js         # Crea un mapper de sistema de archivos para %wwwDir%/js/

Cada mapper crea un FilesystemMapper que:

• Busca archivos en %wwwDir%/<path>
• Genera URLs como %baseUrl%/<path>
• Hereda la configuración global de versionado

Para un mayor control, use la notación detallada:

assets:
	mapping:
		images:
			# directorio donde se almacenan los archivos
			path: ...                    # (string) opcional, por defecto ''

			# prefijo de URL para los enlaces generados
			url: ...                     # (string) opcional, por defecto path

			# ¿habilitar el versionado para este mapper?
			versioning: ...              # (bool) opcional, hereda la configuración global

			# añadir automáticamente extensión(es) al buscar archivos
			extension: ...               # (string|array) opcional, por defecto null

Entendiendo cómo se resuelven los valores de configuración:

Resolución de Rutas

Las rutas relativas se resuelven desde basePath (o %wwwDir% si basePath no está configurado)

Las rutas absolutas se usan tal cual

Resolución de URLs

Las URLs relativas se resuelven desde baseUrl (o %baseUrl% si baseUrl no está configurado)

Las URLs absolutas (con esquema o //) se usan tal cual

Si url no se especifica, usa el valor de path

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

	mapping:
		# Ruta y URL relativas
		images:
			path: img                    # Resuelto a: /var/www/project/www/img
			url: images                  # Resuelto a: https://example.com/assets/images

		# Ruta y URL absolutas
		uploads:
			path: /var/shared/uploads    # Usado tal cual: /var/shared/uploads
			url: https://cdn.example.com # Usado tal cual: https://cdn.example.com

		# Solo la ruta especificada
		styles:
			path: css                    # Ruta: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Mappers Personalizados

Para mappers personalizados, referencie o defina un servicio:

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

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

Vite Mapper

El mapper de Vite solo requiere que añada type: vite. Esta es una lista completa de opciones de configuración:

assets:
	mapping:
		default:
			# tipo de mapper (requerido para Vite)
			type: vite                # (string) requerido, debe ser 'vite'

			# directorio de salida de la construcción de Vite
			path: ...                 # (string) opcional, por defecto ''

			# prefijo de URL para los assets construidos
			url: ...                  # (string) opcional, por defecto path

			# ubicación del archivo manifest de Vite
			manifest: ...             # (string) opcional, por defecto <path>/.vite/manifest.json

			# configuración del servidor de desarrollo de Vite
			devServer: ...            # (bool|string) opcional, por defecto true

			# versionado para archivos del directorio público
			versioning: ...           # (bool) opcional, hereda la configuración global

			# auto-extensión para archivos del directorio público
			extension: ...            # (string|array) opcional, por defecto null

La opción devServer controla cómo se cargan los assets durante el desarrollo:

• true (predeterminado) – Detecta automáticamente el servidor de desarrollo de Vite en el host y puerto actuales. Si el servidor de desarrollo está ejecutándose y su aplicación está en modo depuración, los assets se cargan desde él con soporte para Hot Module Replacement. Si el servidor de desarrollo no está ejecutándose, los assets se cargan desde los archivos construidos en el directorio público.
• false – Deshabilita completamente la integración del servidor de desarrollo. Los assets siempre se cargan desde los archivos construidos.
• URL personalizada (ej. https://localhost:5173) – Especifique manualmente la URL del servidor de desarrollo, incluyendo el protocolo y el puerto. Útil cuando el servidor de desarrollo se ejecuta en un host o puerto diferente.

Las opciones versioning y extension solo se aplican a los archivos del directorio público de Vite que no son procesados por Vite.

Configuración Manual

Cuando no use Nette DI, configure los mappers manualmente:

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

$registry = new Registry;

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

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