Asset handling in TYPO3

Assets usually include CSS files, JavaScript and images / icons used for design purposes.

Within an extension, including a site package, assets can only be placed in folder Resources/Public and subfolders of this folder. This folder will be symlinked into public/_assets/<some hash>.

Note

You must never reference any file in public/_assets directly by using the hash in an absolute or relative URL. The hashes can change at any time. Only use TYPO3 library methods to reference the assets.

Read more about assets in Getting started, assets.

Referencing assets

You can reference assets by prefixing the path with EXT:extension_name, for example EXT:my_site_package.

For example the path to the favicon can be configured in TypoScript like this:

page {
    shortcutIcon = EXT:my_site_package/Resources/Public/Icons/favicon.ico
}

And a CSS asset can be loaded in Fluid using the Asset.css ViewHelper <f:asset.css> like this:

<f:asset.css identifier="main" href="EXT:my_site_package/Resources/Public/Css/main.css" />

Repairing the symlinks from packages/my_site_package/Resources/Public into public/_assets

In case you installed a site package before it had a folder called Resources/Public the symlinks did not get automatically created during Composer installation.

In that case you can tell Composer to re-perform this initialization-process, which is done in the "dump-autoload" step. During that process the symlinks will also be created by Composer.

ddev composer dump-autoload

Managing asset dependencies in real life projects

It is technically possible to use a CDN (Content Delivery Network) to include libraries in TYPO3. However there are privacy and security risks attached to this and it might be a GDPR Violation. Therefore we recommend to host all files yourself by placing them in the Resources/Public folder.

In a later step, you can use npm (Node Package Manager) to manage your JavaScript and CSS dependencies locally. We also recommend using a JavaScript bundler like Vite.

If you decide to use a frontend bundler, make sure that the resulting asset files are placed in a publicly available folder, like Resources/Public in your site package.

There are also TYPO3 extensions like praetorius/vite-asset-collector to bundle your TYPO3 frontend assets with Vite.