Configuración de Assets
***********************

.[perex]
Resumen de las opciones de configuración de Nette Assets.


```neon
assets:
	# ruta base para resolver las rutas relativas de los mappers
	basePath: ...            # (string) el valor predeterminado es %wwwDir%

	# URL base para resolver las URL relativas de los mappers
	baseUrl: ...             # (string) el valor predeterminado es %baseUrl%

	# ¿activar globalmente el versionado de los assets?
	versioning: ...           # (bool) el valor predeterminado es true

	# define los mappers de assets
	mapping: ...             # (array) el valor predeterminado es la ruta 'assets'
```

`basePath` establece el directorio predeterminado del sistema de archivos para resolver las rutas relativas de los mappers. De forma predeterminada usa el directorio web (`%wwwDir%`).

`baseUrl` establece el prefijo de URL predeterminado para resolver las URL relativas de los mappers. De forma predeterminada usa la URL raíz (`%baseUrl%`).

La opción `versioning` controla globalmente si a las URL de los assets se les añaden parámetros de versión para invalidar la caché. Cada mapper puede sobrescribir este ajuste.


Mappers
-------

Los mappers se pueden configurar de tres formas: con la notación sencilla de cadena, con la notación detallada de array, o como servicio (usando la notación de entidad `NombreDeClase(...)` o `@nombreDeServicio()`).

La forma más sencilla de definir un mapper:

```neon
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 los archivos en `%wwwDir%/<path>`
- Genera URL como `%baseUrl%/<path>`
- Hereda el ajuste global de versionado


Para tener más control, use la notación detallada:

```neon
assets:
	mapping:
		images:
			# directorio donde se guardan los archivos
			path: ...                    # (string) opcional, el valor predeterminado es la ruta base (basePath)

			# prefijo de URL de los enlaces generados
			url: ...                     # (string) opcional, el valor predeterminado es path

			# ¿activar el versionado para este mapper?
			versioning: ...              # (bool) opcional, hereda el ajuste global

			# añadir automáticamente la extensión (o extensiones) al buscar los archivos
			extension: ...               # (string|array) opcional, el valor predeterminado es null
```

Así se resuelven los valores de la configuración:

Resolución de la ruta:
   - Las rutas relativas se resuelven a partir de `basePath` (o de `%wwwDir%` si `basePath` no está establecido)
   - Las rutas absolutas se usan tal cual

Resolución de la URL:
   - Las URL relativas se resuelven a partir de `baseUrl` (o de `%baseUrl%` si `baseUrl` no está establecido)
   - Las URL absolutas (con esquema o `//`) se usan tal cual (una URL `//` toma el esquema de `baseUrl`)
   - Si no se indica `url`, se usa el valor de `path`


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

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

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

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


Mappers propios
---------------

Para los mappers propios, referencie un servicio existente con `@nombreDeServicio`, o defínalo directamente con `NombreDeClase(argumentos)` o con el nombre de la clase a secas:

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

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


Mapper de Vite
--------------

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

```neon
assets:
	mapping:
		default:
			# tipo de mapper (obligatorio para Vite)
			type: vite                # (string) obligatorio, tiene que ser 'vite'

			# directorio de salida de la compilación de Vite
			path: ...                 # (string) opcional, el valor predeterminado es la ruta base (basePath)

			# prefijo de URL de los assets compilados
			url: ...                  # (string) opcional, el valor predeterminado es path

			# ubicación del archivo de manifiesto de Vite
			manifest: ...             # (string) opcional, relativo a path, el valor predeterminado es <path>/.vite/manifest.json

			# configuración del servidor de desarrollo de Vite
			devServer: ...            # (bool|string) opcional, el valor predeterminado es true

			# versionado de los archivos del directorio público
			versioning: ...           # (bool) opcional, hereda el ajuste global

			# extensión automática de los archivos del directorio público
			extension: ...            # (string|array) opcional, el valor predeterminado es null
```

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

- `true` (predeterminado): detecta automáticamente si hay un servidor de desarrollo de Vite en marcha (mediante el archivo `.vite/nette.json` que el plugin de Vite de Nette crea en el directorio de compilación). Si el servidor de desarrollo está en marcha **y su aplicación está en modo de depuración**, los assets se cargan de él con soporte de hot module replacement. Si el servidor de desarrollo no está en marcha, los assets se cargan de los archivos compilados del directorio público.
- `false`: desactiva por completo la integración con el servidor de desarrollo. Los assets se cargan siempre de los archivos compilados.
- Una URL propia (p. ej. `https://localhost:5173`): indica manualmente la URL del servidor de desarrollo, incluidos el protocolo y el puerto. Es útil cuando el servidor de desarrollo corre en otro host o puerto. Igual que la detección automática, se aplica solo en modo de depuración; en producción se usan siempre los archivos compilados.

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


Configuración manual
--------------------

Cuando no use Nette DI, configure los mappers a mano:

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

$registry = new Registry;

// Añade un 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ñade un 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',
));
```

También puede obtener por su nombre cualquier mapper registrado con el método `getMapper()`:

```php
$mapper = $registry->getMapper('images');   // devuelve el mapper registrado
$default = $registry->getMapper();           // devuelve el mapper 'default'
```