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 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 the Vite dev server on the current host and port. 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.

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',
));