Configuring Frontend Resource Caching

Liferay DXP 2025.Q4+

When you access a page on your site, the page’s load time depends on how it retrieves frontend resources, such as JavaScript or CSS. Cached files are retrieved faster than files the browser must request from the web server.

Most JavaScript and CSS files in Liferay have hashed file names at build time. For example, a clay.css file may appear at run-time with a hash value in the name (generated based on the file’s contents), like clay.(tvERyCVfuRc).css. This hash value represents a unique version of this file, so the browser can identify that the file’s contents haven’t changed. This allows the file to remain in the cache indefinitely.

The infinite file caching strategy causes each hashed resource to have its own import map entry that is included on each page using it. The infinite caching can reduce requests to the web server and increase performance. However, in some environments, changes to import maps significantly increase page size, negatively impacting performance. Carefully consider the impact on your site’s pages before you enable infinite caching, via the Caching Strategy drop-down menu.

While many resources can be cached indefinitely so they only update when the file is redeployed with changed content, some files always have a limited time-to-live (TTL) in the cache. When this time expires, serving the resource again requires sending a request to the web server to check for an update to the file (and retrieve it, if it exists).

Configuring Frontend Cache Behavior

Configure the cache behavior for your frontend resources in your Instance Settings:

1. Log in as an administrator.

2. Navigate to Applications () → Instance Settings.

3. Under Platform, click Infrastructure.

4. Under Virtual Instance Scope, click Frontend Caching.

On this page, you can configure

Caching Strategy: Choose one hash per resource file or not to use hashed frontend resources. Using one hash per resource file enables infinite file caching.

CSS Style Sheets Max Age Directive Value: The TTL (in seconds) for CSS files. If you enabled infinite file caching, this only applies to CSS files with limited caching. Tokenized CSS files have their own configuration.

JavaScript Files Max Age Directive Value: The TTL (in seconds) for JS files. If you enabled infinite file caching, this only applies to JavaScript files with limited caching. Labels modules and translated JS files have their own configuration.

Labels Modules Max Age Directive Value: The TTL (in seconds) for all.js files with translation labels.

Send No Cache Directive for CSS Style Sheets: Select to force the server to check if each CSS resource has been updated (even if the cached file is valid). If you enabled infinite file caching, this only applies to CSS files with limited caching. Tokenized CSS files have their own configuration.

Send No Cache Directive for JavaScript Files: Select to force the server to check if each JS resource has been updated (even if the cached file is valid). If you enabled infinite file caching, this only applies to JavaScript files with limited caching. Labels modules and translated JS files have their own configuration.

Send No Cache Directive for Labels Modules: Select to force the server to check if each all.js file with translation labels has been updated (even if the cached file is valid).

Send No Cache Directive for Tokenized CSS Style Sheets: Select to force the server to check if each tokenized CSS file has been updated (even if the cached file is valid).

Tokenized CSS Style Sheets Max Age Directive Value: The TTL (in seconds) for tokenized CSS files.

Translated JavaScript Files Max Age Directive Value: The TTL (in seconds) for translated JS files.

Files with Limited Caching

Most out-of-the-box CSS and JavaScript files can be hashed, so they can be cached indefinitely if you enable one hash per resource file. The TTL configurations above do not apply when you enable infinite caching.

However, some files cannot be hashed due to their contents.

CSS Files with Limited Caching

These CSS files cannot be hashed due to their contents, so they always have limited TTL in the cache:

• CSS in custom themes, portlets, or client extensions. It’s up to the developer to hash the file before deploying it.

• CSS files with dynamically replaced tokens (e.g., @base_url@, , or https://learn.lxc.liferay.com/o/dialect-theme/images). These tokens are resolved at runtime, so they can’t be cached indefinitely.

JavaScript Files with Limited Caching

These JS files cannot be hashed due to their contents, so they always have limited TTL in the cache:

• JS in custom themes, portlets, or client extensions. It’s up to the developer to hash the file before deploying it.

• all.js files with translations used by other JS files. They can’t be cached indefinitely because translations can change over time.

• Translated JS files, using Liferay.Language.get() and providing their own resource bundle. These files rely on assets built outside of Liferay DXP, so they can’t use the same process for file hashing.

Related Topics

• Instance Configuration