Nette Documentation Preview

syntax
Assets Configuration
********************

.[perex]
Overview of configuration options for Nette Assets.


```neon
assets:
	# base path for resolving relative mapper paths
	basePath: ...            # (string) defaults to %wwwDir%

	# base URL for resolving relative mapper URLs
	baseUrl: ...             # (string) defaults to %baseUrl%

	# enable asset versioning globally?
	versioning: ...           # (bool) defaults to true

	# defines asset mappers
	mapping: ...             # (array) defaults to path 'assets'
```

The `basePath` sets the default filesystem directory for resolving relative paths in mappers. By default, it uses the web directory (`%wwwDir%`).

The `baseUrl` sets the default URL prefix for resolving relative URLs in mappers. By default, it uses the root URL (`%baseUrl%`).

The `versioning` option globally controls whether version parameters are added to asset URLs for cache busting. Individual mappers can override this setting.


Mappers
-------

Mappers can be configured in three ways: simple string notation, detailed array notation, or as a service (using entity notation `ClassName(...)` or a reference `@serviceName`).

The simplest way to define a mapper:

```neon
assets:
	mapping:
		default: assets     # Creates filesystem mapper for %wwwDir%/assets/
		images: img         # Creates filesystem mapper for %wwwDir%/img/
		scripts: js         # Creates filesystem mapper for %wwwDir%/js/
```

Each mapper creates a `FilesystemMapper` that:
- Looks for files in `%wwwDir%/<path>`
- Generates URLs like `%baseUrl%/<path>`
- Inherits global versioning setting
- Finds only files inside this directory: a reference like `../secret.txt` throws `Nette\Assets\AssetNotFoundException` .{data-version:1.0.8}


For more control, use the detailed notation:

```neon
assets:
	mapping:
		images:
			# directory where files are stored
			path: ...                    # (string) optional, defaults to base path (basePath)

			# URL prefix for generated links
			url: ...                     # (string) optional, defaults to path

			# enable versioning for this mapper?
			versioning: ...              # (bool) optional, inherits global setting

			# auto-add extension(s) when searching for files
			extension: ...               # (string|array) optional, defaults to null
```

Understanding how configuration values are resolved:

Path Resolution:
   - Relative paths are resolved from `basePath` (or `%wwwDir%` if `basePath` is not set)
   - Absolute paths are used as-is

URL Resolution:
   - Relative URLs are resolved from `baseUrl` (or `%baseUrl%` if `baseUrl` is not set)
   - Absolute URLs (with scheme or `//`) are used as-is (a `//` URL gets its scheme from `baseUrl`)
   - If `url` is not specified, it uses the value of `path`


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

	mapping:
		# Relative path and URL
		images:
			path: img                    # Resolved to: /var/www/project/www/img
			url: images                  # Resolved to: https://example.com/assets/images

		# Absolute path and URL
		uploads:
			path: /var/shared/uploads    # Used as-is: /var/shared/uploads
			url: https://cdn.example.com # Used as-is: https://cdn.example.com

		# Only path specified
		styles:
			path: css                    # Path: /var/www/project/www/css
										 # URL: https://example.com/assets/css
```


Custom Mappers
--------------

For custom mappers, reference an existing service with `@serviceName`, or define it directly using `ClassName(arguments)` or a bare class name:

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

assets:
	mapping:
		cloud: @s3mapper          # reference to a service (since 1.0.8)
		database: App\Assets\DatabaseMapper(@database.connection)
```


Vite Mapper
-----------

The Vite mapper only requires you to add `type: vite`. This is a complete list of configuration options:

```neon
assets:
	mapping:
		default:
			# mapper type (required for Vite)
			type: vite                # (string) required, must be 'vite'

			# Vite build output directory
			path: ...                 # (string) optional, defaults to base path (basePath)

			# URL prefix for built assets
			url: ...                  # (string) optional, defaults to path

			# location of Vite manifest file
			manifest: ...             # (string) optional, relative to path, defaults to <path>/.vite/manifest.json

			# Vite dev server configuration
			devServer: ...            # (bool|string) optional, defaults to true

			# versioning for public directory files
			versioning: ...           # (bool) optional, inherits global setting

			# auto-extension for public directory files
			extension: ...            # (string|array) optional, defaults to null
```

The `devServer` option controls how assets are loaded during development:

- `true` (default) - Automatically detects a running Vite dev server (via the `.vite/nette.json` file which the Nette Vite plugin creates in the build directory). If the dev server is running **and your application is in debug mode**, assets are loaded from it with hot module replacement support. If the dev server is not running, assets are loaded from the built files in the public directory.
- `false` - Completely disables the dev server integration. Assets are always loaded from the built files.
- Custom URL (e.g., `https://localhost:5173`) - Manually specify the dev server URL including protocol and port. Useful when the dev server runs on a different host or port. Like auto-detection, it only applies in debug mode; in production the built files are always used.

The `versioning` and `extension` options apply only to files in Vite's public directory that aren't processed by Vite.


Manual Configuration
--------------------

When not using Nette DI, configure mappers manually:

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

$registry = new Registry;

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

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

You can also retrieve any registered mapper by name using the `getMapper()` method:

```php
$mapper = $registry->getMapper('images');   // returns the registered mapper
$default = $registry->getMapper();           // returns the 'default' mapper
```

{{maintitle: Nette Assets Configuration: Mappers, Paths and Versioning}}
{{description: Configure Nette Assets in NEON: the base path and URL, global versioning and the mappers that say where your static files live, including Vite.}}

Assets Configuration

Overview of configuration options for Nette Assets.

assets:
	# base path for resolving relative mapper paths
	basePath: ...            # (string) defaults to %wwwDir%

	# base URL for resolving relative mapper URLs
	baseUrl: ...             # (string) defaults to %baseUrl%

	# enable asset versioning globally?
	versioning: ...           # (bool) defaults to true

	# defines asset mappers
	mapping: ...             # (array) defaults to path 'assets'

The basePath sets the default filesystem directory for resolving relative paths in mappers. By default, it uses the web directory (%wwwDir%).

The baseUrl sets the default URL prefix for resolving relative URLs in mappers. By default, it uses the root URL (%baseUrl%).

The versioning option globally controls whether version parameters are added to asset URLs for cache busting. Individual mappers can override this setting.

Mappers

Mappers can be configured in three ways: simple string notation, detailed array notation, or as a service (using entity notation ClassName(...) or a reference @serviceName).

The simplest way to define a mapper:

assets:
	mapping:
		default: assets     # Creates filesystem mapper for %wwwDir%/assets/
		images: img         # Creates filesystem mapper for %wwwDir%/img/
		scripts: js         # Creates filesystem mapper for %wwwDir%/js/

Each mapper creates a FilesystemMapper that:

For more control, use the detailed notation:

assets:
	mapping:
		images:
			# directory where files are stored
			path: ...                    # (string) optional, defaults to base path (basePath)

			# URL prefix for generated links
			url: ...                     # (string) optional, defaults to path

			# enable versioning for this mapper?
			versioning: ...              # (bool) optional, inherits global setting

			# auto-add extension(s) when searching for files
			extension: ...               # (string|array) optional, defaults to null

Understanding how configuration values are resolved:

Path Resolution
Relative paths are resolved from basePath (or %wwwDir% if basePath is not set)
Absolute paths are used as-is
URL Resolution
Relative URLs are resolved from baseUrl (or %baseUrl% if baseUrl is not set)
Absolute URLs (with scheme or //) are used as-is (a // URL gets its scheme from baseUrl)
If url is not specified, it uses the value of path
assets:
	basePath: /var/www/project/www
	baseUrl: https://example.com/assets

	mapping:
		# Relative path and URL
		images:
			path: img                    # Resolved to: /var/www/project/www/img
			url: images                  # Resolved to: https://example.com/assets/images

		# Absolute path and URL
		uploads:
			path: /var/shared/uploads    # Used as-is: /var/shared/uploads
			url: https://cdn.example.com # Used as-is: https://cdn.example.com

		# Only path specified
		styles:
			path: css                    # Path: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Custom Mappers

For custom mappers, reference an existing service with @serviceName, or define it directly using ClassName(arguments) or a bare class name:

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

assets:
	mapping:
		cloud: @s3mapper          # reference to a service (since 1.0.8)
		database: App\Assets\DatabaseMapper(@database.connection)

Vite Mapper

The Vite mapper only requires you to add type: vite. This is a complete list of configuration options:

assets:
	mapping:
		default:
			# mapper type (required for Vite)
			type: vite                # (string) required, must be 'vite'

			# Vite build output directory
			path: ...                 # (string) optional, defaults to base path (basePath)

			# URL prefix for built assets
			url: ...                  # (string) optional, defaults to path

			# location of Vite manifest file
			manifest: ...             # (string) optional, relative to path, defaults to <path>/.vite/manifest.json

			# Vite dev server configuration
			devServer: ...            # (bool|string) optional, defaults to true

			# versioning for public directory files
			versioning: ...           # (bool) optional, inherits global setting

			# auto-extension for public directory files
			extension: ...            # (string|array) optional, defaults to null

The devServer option controls how assets are loaded during development:

The versioning and extension options apply only to files in Vite's public directory that aren't processed by Vite.

Manual Configuration

When not using Nette DI, configure mappers manually:

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

$registry = new Registry;

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

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

You can also retrieve any registered mapper by name using the getMapper() method:

$mapper = $registry->getMapper('images');   // returns the registered mapper
$default = $registry->getMapper();           // returns the 'default' mapper