Asset Management
AssetService collects the CSS and JavaScript a page needs, renders them as tags in the order they were added, and resolves asset URLs. It can also resolve entries from a Vite build when a Vite manifest or dev server is active.
Use it when a page needs stylesheets or scripts that must be linked from the layout, and the URLs should follow one consistent rule.
For how the frontend build produces these files, see Styles and Assets.
Vite Mode
Vite mode is active when a Vite manifest exists or the Vite dev server is running. ViteResolver provides the @vite alias, and its base defaults to resources/assets.
Reference an entry with the @vite alias or the ~/ prefix:
$asset->viteEntry('@vite/main.ts');When the dev server is running, viteEntry() links the dev server URL. Otherwise it links the built file from the manifest, and it adds the CSS that the manifest lists for that entry.
WARNING
A plain path such as src/main.ts is not resolved as a Vite entry. Use the @vite alias or the ~/ prefix for every Vite entry.
Registering Entries from PHP
Register entries in a controller or middleware. The ~/ prefix and the @vite alias are equivalent:
$this->unicornScript->init('@vite/src/front/main.ts');
$this->asset->css('@vite/scss/front/main.scss');
// Same as above
$this->unicornScript->init('~/src/front/main.ts');
$this->asset->css('~/scss/front/main.scss');@vite/... and ~/ point to the source path, so the Vite resolver handles them.
Compiling Styles
Fusion Next compiles stylesheets. cssModulizeDeep(stage, entry, dest) compiles the stage's entry SCSS and merges every ${stage}/**/assets/*.scss module into it:
// fusionfile.ts
import fusion from '@windwalker-io/fusion-next';
import { cssModulizeDeep } from '@windwalker-io/core/next';
export function css() {
fusion.clean('css/**/*');
return [
cssModulizeDeep(
'Front',
'resources/assets/scss/front/main.scss',
'css/front/main.css'
),
];
}
export default [css];Stage entry files (main.ts, main.scss) are written to the dest you pass, relative to fusion.outDir(). Style and script macros are merged into the stage bundle they belong to.
Images
Put source images under resources/assets/images/. The host's fusionfile.ts copies them to www/assets/images/ with cloneAssets:
// fusionfile.ts
export function images() {
return [
cloneAssets({
'resources/assets/images/**/*': 'images/',
})
];
}Reference an image with the ~/ prefix in each context, so Vite resolves it through the manifest.
In Blade:
<img src="{{ $asset->path('~/images/logo-h.svg') }}" alt="Logo">In TypeScript:
import logo from '~/images/logo-h.svg';
document.querySelector('#logo')?.setAttribute('src', logo);In SCSS:
.hero {
background-image: url('~/images/hero.jpg');
}Use a Vite glob to load many images at once:
// Eager: all URLs are available synchronously.
const icons = import.meta.glob(
'~/images/icons/*.svg',
{ eager: true, import: 'default' }
);
// Lazy: each image is loaded on demand.
const photos = import.meta.glob(
'~/images/photos/*.jpg',
{ import: 'default' }
);Prefixed or Output Paths
- A path that starts with
~/(or@vite/) points to the source file, so it keeps its source extension, such as.ts,.scss, or.svg. Vite compiles it, hashes the output, and looks up the result in the manifest. - A path without a prefix points to the compiled output file name. It works only when you fix the output name explicitly, for example with
destincssModulizeDeep()or a fixed name incloneAssets().
Use a prefixed source path by default. Use an output path only when a file must keep a fixed name, such as a favicon read by external tools.
Adding a Custom Alias
To add an alias such as ~img/, define it in both places:
// fusionfile.ts
fusion.alias('~img', resolve('./resources/assets/images'));// tsconfig.json
{
"compilerOptions": {
"paths": {
"~img/*": ["./resources/assets/images/*"]
}
}
}fusion.alias lets the build resolve the path, and paths lets TypeScript type-check it. Missing either one causes an error.
See Setup and Styles and Assets for the frontend build workflow.
Minimal Usage
Call css() or js() with a path relative to the assets folder, and render the layout's asset output:
$asset->css('css/app.css');
$asset->js('js/app.js');In Edge templates, $asset is available as a global variable. See Edge Templates for details.
Complete Example
This example declares assets in a ViewModel and renders them from a layout.
First, declare the view's own assets with the #[ViewModel] attribute:
use Windwalker\Core\Attributes\ViewModel;
#[ViewModel(
layout: 'index',
css: ['home.css'],
js: ['home.js'],
)]
class HomeView
{
public function prepare(AssetService $asset): void
{
$asset->css('css/vendor/chart.css');
$asset->jsAsync('https://cdn.example.com/lib.js');
}
}The layout adds its shared assets with the same service:
$asset->css('css/app.css');
$asset->js('js/app.js', [], ['defer' => true]);
$asset->module('js/widgets.js');Each call adds a link to the page. Tags are rendered in the order the links were added.
Declaring Assets
Assets are declared in two places: the #[ViewModel] attribute and direct calls to AssetService.
ViewModel Attribute
The #[ViewModel] attribute accepts these asset parameters:
css: stylesheets for the view.js: scripts for the view.modules: ES module scripts for the view.
A single string is cast to a one-item array. Each file is resolved relative to the view's own folder, under the @view alias.
INFO
Entries in js and modules have their extension removed when Vite mode is active. Plain asset mode keeps the file name as written.
For string keys in css, the file applies only when the key equals the current layout name. Numeric keys always apply.
#[ViewModel(
css: [
'base.css',
'index' => 'index.css',
'edit' => 'edit.css',
],
)]In this example, base.css loads for every layout, and index.css loads only for the index layout.
When Vite mode is active, modules is ignored. Put module scripts in js if the page uses Vite.
AssetService Methods
AssetService provides these methods for adding links:
css(url, options, attrs): adds a stylesheet link.footerCSS(url, options, attrs): adds a stylesheet marked for the footer.js(url, options, attrs): adds a script tag.jsAsync(url, options, attrs): adds a script withasync.module(url, options, attrs): adds a script withtype="module".moduleAsync(url, options, attrs): adds a module script withasync.viteEntry(url, options, attrs): adds a Vite entry script and its CSS. It returns an array of links.internalCSS(),internalJS(),internalModule(): add inline content.
The second argument holds link options. The third argument holds HTML attributes:
$asset->js('js/chart.js', [], ['defer' => true]);
$asset->css('css/print.css', [], ['media' => 'print']);WARNING
defer is an HTML attribute, not a link option. Pass it in the third argument. In the second argument, ['defer' => true] is ignored.
module() sets type="module" itself. Do not pass a type attribute for the same script.
Link Options
These options have a meaning in AssetService:
version: set tofalseto skip the cache-busting version.sri: adds anintegrityvalue andcrossoriginto the tag.body: inline content for a script.footer: set byfooterCSS()for stylesheets.
Other keys are stored with the link and are not interpreted.
INFO
Passing footer to js() is stored with the link, but scripts are not moved by that option.
Path Resolution
AssetService converts a URL in this order:
- Aliases are resolved first.
- Vite aliases (
@vite/...or~/...) are resolved when Vite mode is active. - Full URLs (
https://...) are returned unchanged. - Other paths are joined with the assets folder and the asset base URI.
The assets folder is read from the asset.folder config key. It defaults to assets. A leading assets folder in the path is removed before the base is added, so assets/css/app.css and css/app.css resolve to the same file.
For relative paths, AssetService looks for a .min file and a plain file:
- In debug mode, the plain file is preferred, then the
.minfile. - Outside debug mode, the
.minfile is preferred, then the plain file. - If neither exists, the path is used as written.
A missing file does not raise an error.
Path Helpers
Use path() to build a public URL without adding a tag:
$asset->path('images/logo.png');path() with no argument returns the assets base directory with a trailing slash. root() returns the same URL without the host.
Use has() to check a file. It returns the public URL, or false if no file is found. Non-strict mode also checks the .min and plain variants.
Use alias() to define a short name for a path:
$asset->alias('images', '@images');TIP
Use an alias for a folder that appears in many templates. Changing the alias target then updates every reference.
Overriding Upper-Package Paths
An alias also works as a temporary override. A package may hard-code a path such as @vendor/acme/widget/css/widget.css. Your project can point that path to its own file without changing the package:
$asset->alias(
'@vendor/acme/widget/css/widget.css',
'@theme/css/widget.css'
);Every reference to the original path now resolves to the new target. Remove the alias when the package provides a proper configuration option.
WARNING
An alias applies to the whole application, so every view that uses the original path receives the replacement. Check the other views before you add an override.
Versioning and Debug
path() accepts a version as its second argument:
true: uses the current asset version.- A string: appends the string as a query parameter, for example
?v=...or&v=...when a query already exists. false(the default): adds no version.
INFO
In debug mode, the asset version changes on every request. Browsers then fetch the file again each time.
Outside debug mode, the version is read from the file set by the asset.version_file config key. If that file does not exist, AssetService detects a version itself.
Related
- Edge Templates: using
$assetin templates. - View Components: loading assets from a component.
- Renderer: how views are rendered.
- HTML Frame: the page frame that receives assets.
- Styles and Assets: compiling styles, images, and aliases in the frontend build.