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 reference to a service.

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:

• Looks for files in %wwwDir%/<path>
• Generates URLs like %baseUrl%/<path>
• Inherits global versioning setting

For more control, use the detailed notation:

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

			# 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

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 or define a service:

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

assets:
	mapping:
		cloud: @s3mapper
		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 ''

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

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

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

			# 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. When set to true or yes, it uses the current URL with 5173 port (for example http://localhost:5173). You can also specify a custom URL like https://localhost:3000. When enabled and your application is in debug mode, assets are loaded directly from the Vite dev server with hot module replacement support.

Options versioning and extension 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',
));