Joomla Web Asset Manager

The Web Asset Manager (WAM) is a PHP service, Joomla\CMS\WebAsset\WebAssetManager, attached to every HTML document. It sits on top of a WebAssetRegistry that knows every asset that can be loaded, and it keeps track of the assets that will be loaded on the current request. Four kinds of people touch it:

Older material predates it. Tutorials written for Joomla 3 call JHtml::_('jquery.framework'), JHtml::script() or $document->addScript(); the Joomla 4 Developer Manual calls the Document::addScript() and Document::addStyleSheet() family deprecated, to be removed in Joomla 6, and tells you to use the manager instead. The book Joomla! 4 Masterclass (2023) was written for Joomla 4.x and so predates import maps, the removal of the ES5 assets and the nocache version of Joomla 6.1; Developing Extensions for Joomla! 5 (2023) covers the manager itself well but was written for Joomla 5.0 and PHP 8.2, so its version statements need the corrections that follow in this page. What has not changed is the important part: Text::script() and Document::addScriptOptions() are not deprecated and remain the way to hand translated strings and variables to JavaScript.

Everything the manager does happens in three stages.

The two renderers matter because they explain a frequent surprise: an asset activated after the head has been rendered is never output. In a template the <jdoc:include> tags are replaced after index.php ran, so calling useScript() anywhere in index.php, in a layout or in a module is early enough. A call made from a plugin that runs after onBeforeCompileHead is not.

A registry file is plain JSON. The $schema property points at the schema Joomla publishes for editors, and the top-level object has a name, a version, a description, a license, an optional namespace (explained under custom asset classes) and the assets array.

Each entry of assets is an object. The keys you will use are:

Keys that the manager does not interpret are kept as options of the asset and passed along, which is how importmap, weight, deprecated and version work. Unrecognised keys therefore do no harm, but they do nothing either. A missing name or type makes the whole file fail with a RuntimeException, and so does invalid JSON: a stray comma in the template’s joomla.asset.json takes the front end down on every page, not just on the page that uses the asset.

Joomla does not scan the file system for asset files. It reads a fixed list of registry files, in a fixed order, and later definitions replace earlier ones with the same type and name. The order is:

Two consequences follow. First, a template can override any asset a component or the core registered, simply by declaring one with the same name, which is what the overriding section below uses. Second, anything that is not on the list is not loaded automatically. Modules, plugins and layouts that ship a joomla.asset.json must add it themselves with addRegistryFile(), because the manager only reads the files of the active component and template. A module author who forgets this sees an UnknownAssetException as soon as useStyle('mod_tallpine_nexthikes') runs.

The paths given to addRegistryFile() are relative to the site root, for example media/mod_tallpine_nexthikes/joomla.asset.json. A site that uses the public folder (see Installation and the public folder) still writes the same relative path.

The manager is obtained from the document. In a template, the document is $this; elsewhere you ask the application.

Source: Joomla Manual: Web Asset Manager

Inside a class that already has the application (a dispatcher, a plugin with getApplication(), a view with $this->getDocument()), prefer the injected application or document to the static Factory; the call chain is the same.

The calls are generated from three verbs and three types. use, disable, register and registerAndUse combine with Style, Script and Preset, and all return the manager so they can be chained.

The state of an asset is therefore one of inactive, active or dependency. Dependencies are resolved lazily, the first time the manager is asked for its assets or for a state, and again whenever the set of active assets changes. Resolution is recursive; an asset that lists itself is ignored; a missing dependency throws UnsatisfiedDependencyException.

A preset is an asset of type preset whose job is to group others. Its dependencies list names of other assets, each followed by the type to use (name#style or name#script); a preset has no file, so its uri is empty. Activating the preset activates every listed item. The manager methods are usePreset(), disablePreset(), registerPreset() and registerAndUsePreset().

Presets answer a real maintenance problem: Cassiopeia needs a style and a script that always go together, and the left to right and right to left variants differ only in the style. Two presets keep that decision in one place. For the club’s template, template.tallpine does the same for its style and script. If an entry of a preset cannot be found, the manager throws UnsatisfiedDependencyException when the preset is used, not when it is registered. Presets are not sorted: their items are activated in the order listed, and the ordinary dependency sort then arranges the resulting assets.

The order of elements in the page is computed, not written. For each type, the manager takes the active assets plus their dependencies and sorts them with a topological sort: a dependency always comes before the asset that needs it, and assets with no relation to each other come out in the order they were activated (first in, first out), nudged by the weight option when one is present. Cassiopeia gives the owner’s user.css a weight of 500 so that it is last. This has practical rules:

Every asset has a version that controls the query string appended to its URL, so that browsers and proxies fetch a new file after an update.

The query string is added only if the URL does not already contain a ?. The same rule applies to the src of the import map. For nocache the manifest is simply "version": "nocache":

Source: Joomla Manual: Web Asset Manager

The nocache value is a development tool. In production it defeats browser caching for that asset and, because the URL changes on every request, a reverse proxy or CDN cannot cache the page’s references to it consistently either; remove it before going live (see Caching and performance). A template that must also run on Joomla 5.4 should not rely on the value there, because the 6.1 release notes and Manual place it in the 6.x line; set a fixed version through registerAndUseStyle(..., ['version' => ...]) from PHP for that case.

Everything in attributes is copied to the element. The commonly useful ones are:

Source: Joomla Manual: Web Asset Manager

This module-plus-legacy-fallback pattern is how Joomla itself shipped assets in Joomla 4. In Joomla 5.0 the project dropped the ES5 builds of its own assets: modern browsers all understand modules, so the nomodule variants of core assets were removed. The consequences are practical. Third-party extensions and old templates that depended on a core ES5 asset by name must stop; new assets should be written as modules and need no fallback unless the club genuinely supports a browser without module support, which is not the case for any browser Joomla 6 itself supports. Where you still use a nomodule script, keep it a leaf dependency of the module, as above. In a debug session core assets carry data-asset-name and data-asset-dependencies attributes so you can see which asset produced which element.

For script assets, a boolean attribute written as true is output as a bare attribute. If a template needs a non-boolean attribute at run time, $wa->getAsset('style', 'fontawesome')->setAttribute('rel', 'lazy-stylesheet') sets it on the registry item, as Cassiopeia’s own index.php does.

Sometimes the content is not a file: a few CSS custom properties computed from template parameters, or a three-line initialisation script. addInlineStyle() and addInlineScript() register an inline asset:

Source: Joomla Manual: Web Asset Manager

The rules, all from the Manual and the renderer:

Inline code is a security surface, so treat it as one. If the content includes any value that came from a request, a database row or a parameter, it must be validated or encoded for its context, as in the colour check above. Where the data is more than a fixed constant, do not build JavaScript with string concatenation: put the data in addScriptOptions() and read it with Joomla.getOptions('com_tallpine.map'), and put translatable text in Text::script(). When a Content Security Policy is active (see Security hardening, MFA and passkeys), inline assets are the first thing it blocks; Joomla adds the document’s CSP nonce to every script and style element it renders when one is set, which is another reason to use the manager rather than printing <script> tags in a layout.

A script asset declared with "type": "module" is a native ES module. Modules can import each other by bare names (import {x} from 'tallpine-map'), and browsers resolve those names with an import map, a JSON block in the page head. Joomla builds the import map for you from the registry.

Add "importmap": true to a script asset and Joomla includes it in the map. Two optional options refine it: importmapName sets the name other modules import (the default is the asset name) and importmapScope limits the entry to modules loaded from a path. This arrived with Joomla 5.0, together with the polyfill that makes import maps work in older browsers; core itself uses it for the editor API (editor-decorator, editor-api) and the dialog (joomla.dialog).

Source: Joomla Manual: Web Asset Manager

The renderer emits the import map first, before any <script> element, as <script type="importmap"> with a JSON body mapping each name to the asset’s URL (with its version query string), plus a scopes object for scoped entries. The map must come before the first module that uses it, which is why Joomla renders it before the regular scripts. The same version rules apply to its URLs. Because the browser only reads the first import map in a document, do not add your own <script type="importmap"> to a layout: register an asset instead. An entry in the map does not load the file, it only names it; the file loads when a module imports it, or when the asset is also used so that a <script> element is emitted.

Joomla ships a loader for custom elements (joomla-alert, joomla-tab, joomla-field-media and so on). By convention the asset is called webcomponent.<name>, is a module script plus a style, and is loaded asynchronously by the Web Component loader instead of as an ordinary script. A fallback for browsers without module support lists a nomodule script that depends on the wcpolyfill asset; Joomla 6.0 removed the polyfill asset, and the Behaviour - Backward Compatibility 6 plugin keeps an empty placeholder with that name (and for the dropped chosen assets) so that an old useScript('wcpolyfill') call does not throw. In PHP the pair is registered as a style plus a module script and then used together.

Source: Joomla Manual: Web Asset Manager

The cleanest way to change what Joomla loads is the registry: define an asset with the same type and name in a file that is read later. Because the child template’s file is read last, that is the natural place.

The Developer Manual lists Document::addScript(), Document::addStyleSheet() and the related addScriptDeclaration() and addStyleDeclaration() calls as deprecated, with removal scheduled for Joomla 6, and the manager as the replacement. In practice, treat every remaining call as technical debt: they bypass dependency resolution, have no version control and are output in a different part of the renderer. The mapping is mechanical:

The compatibility rules for the move to Joomla 6, including how the Backward Compatibility 6 plugin helps while you migrate, are in Upgrading from Joomla 5 to 6 and Deprecations and preparing for Joomla 7.

The default item class is Joomla\CMS\WebAsset\WebAssetItem. An asset can name another class with class (and optionally namespace), which must implement WebAssetItemInterface or extend WebAssetItem. The namespace set at the top of the file applies to every item, a namespace on an item overrides it, and with none given the default namespace is Joomla\CMS\WebAsset; an explicitly empty namespace means the class name is used as it is. Joomla uses this for core (CoreAssetItem), the keepalive script and Cassiopeia’s language-specific stylesheet (LangActiveAssetItem). Two reasons to write one:

With Docker Compose running (see Local development with Docker), two checks cover most problems. Switch on System > Global Configuration > Debug System, then look at the generated head: assets carry data-asset-name and data-asset-dependencies.

Source: Joomla Manual: Web Asset Manager

The Chrome or Firefox network panel then shows whether the child template’s files returned 200 or 404; a 404 for media/templates/site/cassiopeia_tallpine/css/tallpine.css means the file is missing from the template’s media folder or the <media> element of templateDetails.xml does not list its css folder. See Debugging for the debug bar and the log.