Configuração de Assets

Visão geral das opções de configuração para Nette Assets.

assets:
	# caminho base para resolver caminhos de mapper relativos
	basePath: ...            # (string) padrão para %wwwDir%

	# URL base para resolver URLs de mapper relativas
	baseUrl: ...             # (string) padrão para %baseUrl%

	# habilitar versionamento de asset globalmente?
	versioning: ...           # (bool) padrão para true

	# define os mappers de asset
	mapping: ...             # (array) padrão para o caminho 'assets'

O basePath define o diretório padrão do sistema de arquivos para resolver caminhos relativos em mappers. Por padrão, ele usa o diretório web (%wwwDir%).

A baseUrl define o prefixo de URL padrão para resolver URLs relativas em mappers. Por padrão, ele usa a URL raiz (%baseUrl%).

A opção versioning controla globalmente se os parâmetros de versão são adicionados às URLs dos assets para cache busting. Mappers individuais podem substituir essa configuração.

Mappers

Mappers podem ser configurados de três maneiras: notação de string simples, notação de array detalhada ou como uma referência a um serviço.

A maneira mais simples de definir um mapper:

assets:
	mapping:
		default: assets     # Cria um mapper de sistema de arquivos para %wwwDir%/assets/
		images: img         # Cria um mapper de sistema de arquivos para %wwwDir%/img/
		scripts: js         # Cria um mapper de sistema de arquivos para %wwwDir%/js/

Cada mapper cria um FilesystemMapper que:

• Procura arquivos em %wwwDir%/<path>
• Gera URLs como %baseUrl%/<path>
• Herda a configuração de versionamento global

Para mais controle, use a notação detalhada:

assets:
	mapping:
		images:
			# diretório onde os arquivos são armazenados
			path: ...                    # (string) opcional, padrão para ''

			# prefixo de URL para links gerados
			url: ...                     # (string) opcional, padrão para path

			# habilitar versionamento para este mapper?
			versioning: ...              # (bool) opcional, herda a configuração global

			# adicionar automaticamente extensão(ões) ao procurar arquivos
			extension: ...               # (string|array) opcional, padrão para null

Entendendo como os valores de configuração são resolvidos:

Resolução de Caminho

Caminhos relativos são resolvidos a partir de basePath (ou %wwwDir% se basePath não estiver definido)

Caminhos absolutos são usados como estão

Resolução de URL

URLs relativas são resolvidas a partir de baseUrl (ou %baseUrl% se baseUrl não estiver definido)

URLs absolutas (com esquema ou //) são usadas como estão

Se url não for especificado, ele usa o valor de path

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

	mapping:
		# Caminho e URL relativos
		images:
			path: img                    # Resolvido para: /var/www/project/www/img
			url: images                  # Resolvido para: https://example.com/assets/images

		# Caminho e URL absolutos
		uploads:
			path: /var/shared/uploads    # Usado como está: /var/shared/uploads
			url: https://cdn.example.com # Usado como está: https://cdn.example.com

		# Apenas o caminho especificado
		styles:
			path: css                    # Caminho: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Mappers Personalizados

Para mappers personalizados, faça referência ou defina um serviço:

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

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

Vite Mapper

O mapper Vite exige apenas que você adicione type: vite. Esta é uma lista completa de opções de configuração:

assets:
	mapping:
		default:
			# tipo de mapper (obrigatório para Vite)
			type: vite                # (string) obrigatório, deve ser 'vite'

			# diretório de saída de construção do Vite
			path: ...                 # (string) opcional, padrão para ''

			# prefixo de URL para assets construídos
			url: ...                  # (string) opcional, padrão para path

			# localização do arquivo de manifesto do Vite
			manifest: ...             # (string) opcional, padrão para <path>/.vite/manifest.json

			# configuração do servidor de desenvolvimento do Vite
			devServer: ...            # (bool|string) opcional, padrão para true

			# versionamento para arquivos do diretório público
			versioning: ...           # (bool) opcional, herda a configuração global

			# auto-extensão para arquivos do diretório público
			extension: ...            # (string|array) opcional, padrão para null

A opção devServer controla como os assets são carregados durante o desenvolvimento:

• true (padrão) – Detecta automaticamente o servidor de desenvolvimento Vite no host e porta atuais. Se o servidor de desenvolvimento estiver em execução e sua aplicação estiver em modo de depuração, os assets são carregados dele com suporte a hot module replacement. Se o servidor de desenvolvimento não estiver em execução, os assets são carregados dos arquivos construídos no diretório público.
• false – Desativa completamente a integração do servidor de desenvolvimento. Os assets são sempre carregados dos arquivos construídos.
• URL personalizada (por exemplo, https://localhost:5173) – Especifique manualmente a URL do servidor de desenvolvimento, incluindo protocolo e porta. Útil quando o servidor de desenvolvimento é executado em um host ou porta diferente.

As opções versioning e extension aplicam-se apenas a arquivos no diretório público do Vite que não são processados pelo Vite.

Configuração Manual

Quando não estiver usando Nette DI, configure os mappers manualmente:

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

$registry = new Registry;

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

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