Why Liferay Pages Score Poorly in Lighthouse and How to Optimize Performance

A low Google Lighthouse score on your Liferay website can point to issues that go beyond page loading speed. Large images, unnecessary scripts, slow server responses, and poorly optimized components can affect how quickly pages appear, how smoothly users interact with them, and how search engines assess page experience.

Liferay performance optimization starts with understanding what slows a page down, not applying fixes without identifying the cause. A high Lighthouse score alone doesn't guarantee a good user experience, just as a low score doesn't always indicate a problem across the entire website.

The key is to interpret performance metrics, identify the underlying bottlenecks, and prioritize changes that make a measurable difference. This guide explains why Liferay pages score poorly in Lighthouse, how to diagnose common issues, and which practical steps can help improve website performance and Core Web Vitals.

Why Do Liferay Pages Score Poorly in Lighthouse?

A low Lighthouse score on a Liferay website can stem from several issues, not a single performance bottleneck. Large images, unnecessary CSS and JavaScript, third-party scripts, and slow server responses can affect how quickly a page loads and how smoothly visitors interact with it. Custom themes, fragments, widgets, and client extensions can also contribute when they add resources a page doesn't need.

Understanding these causes is essential for effective Liferay website performance optimization. Instead of applying the same fixes across every page, developers need to identify which resources or components are affecting performance and address them accordingly. The following issues are among the most common reasons Liferay pages receive poor Lighthouse scores.

The most common issues include:

• Large images and delayed content loading: Oversized images, particularly hero banners, can delay the appearance of important page content and affect Largest Contentful Paint (LCP).
• Excessive CSS and JavaScript: Unused stylesheets, unnecessary scripts, and resources loaded across every page can increase download time and delay rendering or interaction.
• Third-party scripts: Chat widgets, analytics tools, and embedded videos can consume browser resources and affect page responsiveness.
• Unexpected layout shifts: Images without defined dimensions, dynamically loaded content, and banners that push existing content down can contribute to Cumulative Layout Shift (CLS).
• Slow server responses and component rendering: Uncached components and large, unpaginated collections can increase the time required to deliver a page.

Effective Liferay website performance optimizations start with measuring current results, identifying bottlenecks, and applying evidence-based fixes. Liferay's Page Audit tool can help locate slow-rendering components and highlight potential configuration issues.

For persistent issues involving custom themes, fragments, or application components, Liferay Development Services may also be relevant when code-level investigation is required.

How to Diagnose Liferay Website Performance Issues

Before making changes to a Liferay website, understand what affects its performance. A low Lighthouse score does not automatically mean every page has the same problem. One page may struggle with large images, while another may load unnecessary JavaScript or take too long to render its components. A structured assessment helps identify these differences and prioritize the fixes that matter most.

Measure Performance Using Google Lighthouse

Start by running Google Lighthouse on key pages of your Liferay website, including the homepage, landing pages, and content-heavy pages. Test mobile performance first, as limited processing power and network conditions can reveal issues that may be less noticeable on desktop.

Review the Performance score alongside individual metrics, including Largest Contentful Paint (LCP), Total Blocking Time (TBT), and Cumulative Layout Shift (CLS). These measurements help identify whether the main concerns involve content loading, browser responsiveness, or unexpected layout movement.

For more reliable comparisons, run tests under consistent conditions and record the initial results before implementing changes.

Use Liferay Page Audit to Identify Slow Components

Google Lighthouse helps identify browser-level performance issues, but it may not pinpoint which Liferay component is contributing to the problem. The Page Audit tool in Liferay DXP can provide additional insight.

Use the Liferay Page Audit tool to review component render times, cache status, and potential performance issues. This helps identify components that may require further investigation, including widgets and collection displays that load large amounts of content.

Compare Lighthouse Results with Real-User Data

Lighthouse runs controlled tests in a lab environment, whereas real-user data reflects how visitors experience your website under different devices, network conditions, and usage patterns.

Review PageSpeed Insights and Google Search Console to understand how your pages perform for actual users. Pay particular attention to the Core Web Vitals results, as they provide additional context that a single Lighthouse test cannot offer.

Comparing Lighthouse results with real-user data helps identify performance bottlenecks and prioritize fixes based on their impact. For complex portals, Liferay portal assessment and performance-tuning can help teams investigate persistent issues and determine the appropriate improvements.

How to Improve Largest Contentful Paint (LCP) on Liferay Pages

Largest Contentful Paint (LCP) measures how quickly the largest visible content element appears on a page. On many Liferay pages, this is the hero image at the top. When it takes too long to load, visitors may see a blank space or incomplete content for longer than expected. Effective Liferay performance optimization starts with identifying this element and understanding what delays its appearance.

Use Correctly Sized Images

Large images can increase loading time, particularly when full-size files appear in smaller banners or cards. For better Liferay page speed optimization, use images close to their intended display dimensions, leverage Liferay Adaptive Media to generate smaller versions for different screen sizes, and consider modern formats such as WebP where appropriate.

Avoid Lazy Loading the Hero Image

Lazy loading is useful for images lower down the page because they do not need to load immediately. However, applying it to the hero image can delay the main content visitors see first. Keep lazy loading disabled for the hero image and enable it for images further down the page.

<img
  src="/documents/hero-banner.webp"
  alt="Product overview"
  width="1440"
  height="600"
  fetchpriority="high"
  loading="eager"
/>

Where necessary, use fetchpriority="high" and loading="eager" to help the browser prioritize the hero image. Apply high fetch priority to only one critical image to avoid competing priorities.

Load Fonts Efficiently

Fonts can also affect how quickly text becomes visible. Use WOFF2 font files, include only the font weights required by the page, and apply font-display: swap so text can appear while the preferred font is loading.

Reduce CSS and JavaScript

Excess CSS and JavaScript can increase the amount of work a browser must perform when loading a Liferay page. Custom themes, modules, global client extensions, and third-party scripts can contribute to this overhead. Reviewing these resources helps identify opportunities to improve page performance.

Use a Minified, Production-Built Theme

Minify your theme's CSS and JavaScript during the build process using Liferay Workspace or Gradle. Liferay's own resources are already minified, so additional page weight often comes from custom themes and modules. Ensure your live website serves production files rather than development files.

Remove Unused CSS

Themes may include styles that are no longer needed or are not used on a particular page. In Chrome DevTools, open the Coverage tab and reload the page to identify unused CSS. Review the results before removing unnecessary styles.

Break Down Responsive CSS and Load by Screen Size

Load Breakpoint-Specific CSS Conditionally to Eliminate Render-Blocking Styles

In traditional Liferay theme development, responsive styles for mobile, tablet, and desktop views are bundled into a single monolithic CSS file (main.css or custom.css). Because browsers treat standard <link rel="stylesheet"> tags as render-blocking resources, mobile visitors are forced to download, parse, and evaluate extensive desktop styles—such as mega menus and multi-column navigation—before the browser can render anything on screen. This significantly delays First Contentful Paint (FCP) and hurts mobile Lighthouse performance.

A practical solution is to split large component styles into dedicated breakpoint files inside your theme and load them conditionally using the media attribute.

Step 1: Organize Breakpoint-Specific Files in Your Theme

Instead of placing all media queries inside one file, split the component's CSS inside your theme’s src/css/ directory:

themes/your-theme/src/css/common-components/header/
├── header-navigation-main.css   /* Base desktop styles (min-width: 1200px) */
├── header-navigation-1199.css   /* Styles for viewports up to 1199px */
├── header-navigation-991.css    /* Tablet viewports (768px - 991px) */
├── header-navigation-767.css    /* Mobile landscape (576px - 767px) */
└── header-navigation-575.css    /* Mobile portrait (max-width: 575px) */

Step 2: Conditionally Link Stylesheets in portal_normal.ftl

In your theme's src/templates/portal_normal.ftl inside the <head> section, include these files with explicit media attributes:

<link rel="stylesheet" href="${css_folder}/common-components/header/header-navigation-main.css" media="screen and (min-width: 1200px)" />
<link rel="stylesheet" href="${css_folder}/common-components/header/header-navigation-1199.css" media="screen and (max-width: 1199px)" />
<link rel="stylesheet" href="${css_folder}/common-components/header/header-navigation-991.css" media="screen and (min-width: 768px) and (max-width: 991px)" />
<link rel="stylesheet" href="${css_folder}/common-components/header/header-navigation-767.css" media="screen and (min-width: 576px) and (max-width: 767px)" />
<link rel="stylesheet" href="${css_folder}/common-components/header/header-navigation-575.css" media="screen and (max-width: 575px)" />

How This Affects Lighthouse and Browser Rendering:

• Bypasses the Critical Rendering Path: When the browser encounters a stylesheet whose media query does not match the current viewport (for example, min-width: 1200px on a mobile device), it continues downloading the file at lowest priority in the background, but it will not block rendering.
• Resolves “Eliminate Render-Blocking Resources”: Lighthouse tests pages using simulated mobile viewports (typically 360–412px wide). Only header-navigation-575.css blocks the initial paint; the heavy desktop styles are treated as non-blocking.
• Reduces Main Thread Style Calculation: The browser does not spend critical CPU cycles computing unneeded desktop navigation rules before the first paint, delivering a much faster First Contentful Paint (FCP) and Largest Contentful Paint (LCP).

Load Scripts Only Where They Are Needed

Global CSS and JavaScript client extensions load across pages. Use them only for code that every page requires. If a script supports a specific component, such as a slider or filter, add it to that fragment so it loads only on pages that use it.

Defer Non-Critical JavaScript to Cut Total Blocking Time (TBT)

Defer Theme Scripts and Third-Party Trackers

By default, when a browser encounters a standard <script src="..."> tag, it immediately halts HTML parsing while the script is downloaded and executed. In Liferay websites that rely on third-party libraries (such as carousels, popup modals, or analytics tags), this pause causes high Total Blocking Time (TBT) and delays the execution of core page logic.

Using the defer attribute ensures that scripts download asynchronously in parallel with HTML parsing and execute only after the entire DOM is constructed, preserving their original order.

Applying defer to Theme Scripts in portal_normal.ftl

Place non-critical scripts near the bottom of portal_normal.ftl before the closing </body> tag and append the defer attribute:

<!-- Deferred theme utilities and component libraries -->
<script defer src="${javascript_folder}/owl.carousel.min.js"></script>
<script defer src="${javascript_folder}/pages/contact-us/contact-us-form.js"></script>

Deferring Third-Party Analytics and Client Extensions

Third-party tracking scripts such as Microsoft Clarity, Google Tag Manager, or Google Analytics often trigger high CPU usage and long tasks during initial page load.

When injecting scripts dynamically (via theme templates or Liferay JavaScript Client Extensions), ensure defer = true is explicitly configured:

// Example: Deferring Microsoft Clarity in portal_normal.ftl
t = l.createElement(r);
t.defer = 1;
t.src = "https://www.clarity.ms/tag/" + i;
y.parentNode.insertBefore(t, y);

// Example: Deferring GTM / GA4 in a Liferay JS Client Extension
const script = document.createElement("script");
script.defer = true;
script.src = "https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX";
document.head.appendChild(script);

How This Affects Lighthouse and Core Web Vitals:

• Reduces Total Blocking Time (TBT) and Improves INP: Deferring scripts keeps the main browser thread idle while the user sees the initial content, allowing the page to respond immediately to clicks, taps, or scrolls.
• Eliminates Script-Level Render-Blocking: The browser can parse and paint the hero element (LCP) without waiting for slider plugins, form validation scripts, or analytics code to execute.

Control Third-Party Scripts

Chat widgets, tag managers, and embedded videos can affect page performance. To reduce their impact:

• Remove tags and tools you no longer use.
• Load chat and feedback widgets after the page has finished loading.
• Show a video thumbnail first and load the player only when a visitor clicks on it.

Reviewing these resources can help reduce unnecessary browser work while preserving the functionality visitors need.

Prevent Layout Shifts (CLS) on Liferay Pages

A page may load its content quickly and still deliver a frustrating experience if elements move unexpectedly while visitors are reading or interacting with it. Cumulative Layout Shift (CLS) measures these unexpected movements. On Liferay websites, they can occur when images load without reserved space, banners push content down, or embedded elements change the page layout after loading.

Improving Liferay Core Web Vitals involves identifying these shifts and ensuring the page layout accounts for content before it appears.

Set Image Dimensions

Specify image dimensions or define an aspect ratio so the browser can reserve the required space before an image loads. This helps prevent surrounding content from moving when the image appears.

Manage Banners and Embedded Content

Cookie notices and announcement banners should overlay the page or have reserved space rather than unexpectedly push existing content down. Similarly, provide sufficient space for forms, maps, and videos to prevent sudden layout changes when these elements load.

Use a Suitable Fallback Font

Choose a fallback font with characteristics similar to the primary font. This helps reduce noticeable text movement when the browser loads the final font.

For a Liferay fragment displaying a hero image, the following CSS example defines the image dimensions and aspect ratio:

.fragment-hero-image {
  width: 100%;
  height: auto;
  aspect-ratio: 12 / 5;
  object-fit: cover;
}

The aspect-ratio property helps the browser reserve the intended space for the image, while object-fit: cover controls how the image fills that area. Together, these settings help maintain the intended layout as the image loads.

Improve Caching and Server Response

Even when a Liferay page is well optimized on the frontend, a slow server response can delay the entire loading process. If image optimization and CSS or JavaScript improvements have not resolved the issue, review the website's caching settings and identify components that may be taking too long to render.

Enable Frontend Caching

Liferay allows CSS and JavaScript files to be cached for extended periods, reducing the need for returning visitors to download the same resources repeatedly. You can configure this through the Frontend Caching settings in your virtual instance.

According to Liferay's documentation, infinite caching for JavaScript files requires DXP 2026.Q1 or later. Check out the official frontend resource caching documentation for the configuration options available in your version.

Use a Content Delivery Network (CDN)

A content delivery network (CDN) serves resources such as images, fonts, CSS, and JavaScript from servers closer to visitors, helping reduce delivery times. Liferay PaaS and SaaS include a CDN for delivering website resources.

However, caching rules must be configured carefully. Private or personalized pages should not be cached in a way that could expose one visitor's information to another.

Identify and Fix Slow Components

Liferay warns that collection displays containing more than 200 items can experience significant performance issues. Enabling pagination helps limit the number of items displayed at once and reduces the amount of content the page needs to process.

Reviewing frontend caching, resource delivery, and component rendering together helps identify whether delays come from resource downloads or how the page is generated.

Quick Reference: Lighthouse Audit Findings and Liferay Fixes

A Lighthouse report can highlight several performance issues, but knowing which Liferay setting, component, or resource to review is essential for addressing them effectively. The following table connects common Lighthouse audit findings with their potential causes in Liferay and the corresponding areas to investigate.

Use it as a practical reference when prioritizing Liferay performance optimization, so you can move from identifying a warning to finding a relevant fix without making unnecessary changes across the website.

Liferay Website Performance Optimization Checklist

Use this checklist to review the key areas that affect Liferay website performance and confirm that the main optimization tasks have been addressed.

• Run mobile Lighthouse tests on key page types and record the initial results.
• Compare Lighthouse findings with real-user data in PageSpeed Insights and Google Search Console.
• Resize images, use Adaptive Media where appropriate, and ensure the hero image loads eagerly.
• Minify theme assets, remove unused CSS, and limit global JavaScript to functionality required across the website.
• Remove unnecessary third-party scripts or delay loading non-essential resources.
• Reserve space for images, banners, and embedded content to prevent unexpected layout shifts.
• Review frontend caching and CDN configuration for static resources.
• Enable pagination on collection displays to avoid loading too many items at once.
• Retest affected pages after implementing changes and compare the results.

Conclusion

Improving Lighthouse scores on a Liferay website requires more than addressing individual warnings. It starts with understanding how images, CSS, JavaScript, page components, and caching affect the overall loading experience. Identifying the actual bottlenecks helps development teams prioritize changes that matter rather than making unnecessary adjustments across the website.

Effective Liferay performance optimization also requires consistent testing. Measure performance before making changes, address the biggest issues first, and retest affected pages to confirm the changes delivered the expected results. Comparing Lighthouse reports with real-user data provides a clearer picture of how the website performs in practice.

By following a structured approach, teams can improve page loading, responsiveness, and visual stability while maintaining essential website functionality. Regular performance reviews can also help identify emerging issues before they affect the visitor's experience.

Frequently Asked Questions

What is a good Lighthouse score for a Liferay DXP site?

A Lighthouse score of 90 or higher is generally considered good, but the score alone does not determine website performance. Review Core Web Vitals alongside the score to understand how quickly pages load, respond to interactions, and maintain visual stability.

Why is my mobile score lower than my desktop score?

Mobile Lighthouse tests simulate slower network conditions and less powerful processing capabilities than typical desktop tests. Large images, unnecessary JavaScript, and resource-heavy components can therefore have a greater impact on mobile performance. Testing mobile pages first helps identify these issues.

Should I lazy-load all images on my Liferay website?

No. Lazy loading is useful for images further down the page because they do not need to load immediately. Keep the hero image eager-loaded when it is the main visible content, so lazy loading does not delay its appearance.

How do I find which Liferay component is slowing down a page?

Use the Liferay Page Audit tool to review component render times, cache status, and potential performance warnings. This helps identify components that may require further investigation, including widgets and collection displays that load large amounts of content.

How long does Search Console take to show performance improvements?

Search Console's Core Web Vitals reports use real-user data collected over a rolling 28-day period. Improvements may therefore take time to become visible, depending on when sufficient new data is collected and how frequently visitors access the affected pages.

Do Lighthouse scores improve Core Web Vitals?

Improving Lighthouse results can help identify and address issues affecting Core Web Vitals, but the two are not interchangeable. Lighthouse uses controlled lab tests, while Core Web Vitals field data reflects actual user experiences across different devices and network conditions.