Client Extensions in Liferay: how the front end says goodbye to OSGi modules

Client Extensions in Liferay: how the front end says goodbye to OSGi modules
Liferay and portals
Alejandro Muñoz del Prado

Alejandro Muñoz del Prado

Equipo técnico

November 16, 2026
5 min read
Share:

For years, any interface piece in Liferay (a portlet, a widget, even a simple standalone JavaScript fragment) ended up packaged into an OSGi module. It worked, but the cost was high: learning the OSGi lifecycle, dealing with bnd.bnd, waiting for the module to resolve its dependencies and, often, fighting with library versions that the portal itself already included. For a frontend developer coming from React, Vue, or simply modern JavaScript, that leap was a real barrier.

Client Extensions remove that barrier. They are Liferay DXP's way (since version 7.4) of deploying frontend code without touching OSGi: a declarative package, described in a client-extension.yaml file, that the portal registers and serves as if it were any other static resource. There's no OSGi container involved, no need to wait for a bundle to start up, and the development cycle looks a lot more like that of any current frontend project: build, zip, deploy.

Why Liferay is betting on this model

The change has practical consequences. Separating the frontend from the OSGi backend allows a frontend team to work with their usual stack (React, Vue, webpack, Vite) without needing to understand Java or the lifecycle of Liferay services. And it enables something equally important: that code can be deployed independently, with its own pipeline, without dragging along a full rebuild of the portal.

In our work with Liferay DXP, this translates into projects that are easier to split up: whoever does the frontend delivers their client extension, whoever does the backend keeps working on their OSGi modules when they're really needed (business logic, services, integrations), and both converge on the same portal without stepping on each other. For part of that initial scaffolding, the configuration files and the folder structure, we use AI agents that generate the base following Liferay's templates; the final review of what gets deployed is always done by a person.

The types of Client Extension you'll come across

Not all of them serve the same purpose. Liferay defines several types, and the common mistake is trying to force one for a case that calls for another:

  • •customElement: the most widely used. It registers a custom HTML element (a web standard custom element) that can render React, Vue, or vanilla JavaScript. It's the natural path for interactive widgets that would previously have been a portlet.
  • •themeCSS: injects additional stylesheets into the active theme without having to recompile or deploy a new theme. Useful for one-off branding tweaks or to override the styles of a specific component.
  • •globalJS: loads a JavaScript script on every page of the portal. Designed for cross-cutting utilities (analytics, polyfills, small integrations) that don't need their own interface.
  • •oAuthApplication: registers an OAuth2 application so external services (or the frontend itself) can consume Liferay's headless APIs without going through classic session authentication.
  • •batch: encapsulates processes that run on a schedule or on demand, such as bulk data imports, without needing an OSGi module with its own scheduler.

In practice, 80% of the frontend work in a current Liferay project goes through customElement. That's why it deserves a complete example.

Portals and applications built to last for years. And someone to maintain them.

We build and maintain portals, intranets and applications. And we rescue existing ones: we update them, tidy them up and leave them maintainable.

See portals and development

A custom element in React, step by step

Let's build a simple widget, a course listing, following the same structure used in Liferay's official examples in their client-extensions repositories (both in cis/client-extensions and in portal/client-extensions, where we find already solved cases such as training-courses or satisfaction-survey). They're a must-read reference before writing a single line of your own: they resolve in advance packaging and communication-with-the-portal doubts that, otherwise, get discovered through trial and error.

The client-extension.yaml file

Every client extension starts here. This file describes what gets deployed and how it integrates with the portal:

YAML
assemble:
  - from: build
    into: static

trainingCoursesCE:
  name: Training Courses List
  type: customElement
  portletCategoryName: category.sample
  htmlElementName: training-courses
  urls:
    - training-courses.js
  cssURLs:
    - training-courses.css
  useESM: true
  instanceable: true

Two details really matter. The assemble block indicates which build output folder gets packaged as a static resource: if you point to the wrong folder, the deploy doesn't fail, but the element won't find its JavaScript at runtime. And htmlElementName is the name of the custom element exactly as you'll use it on a page or fragment: <training-courses></training-courses>.

The React component

The entry point registers the custom element in the browser. No Liferay framework is needed inside the component, just the standard customElements API:

JavaScript
import React from 'react';
import { createRoot } from 'react-dom/client';
import TrainingCourses from './TrainingCourses';

class TrainingCoursesElement extends HTMLElement {
  connectedCallback() {
    this.root = createRoot(this);
    this.root.render(<TrainingCourses />);
  }

  disconnectedCallback() {
    this.root?.unmount();
  }
}

if (!customElements.get('training-courses')) {
  customElements.define('training-courses', TrainingCoursesElement);
}

The TrainingCourses component is plain, ordinary React: it can call Liferay's headless APIs with fetch, render a list, paginate. If the custom element needs to authenticate against an external API, we do that with a separate oAuthApplication, not mixed into this same package.

Build and deployment

The build is that of any React project with webpack or Vite, generating the artifacts in the build folder that client-extension.yaml expects. The Liferay-specific step is packaging and deploying that result together with the yaml:

Bash
npm run build
liferay-cli deploy

The deploy command packages the client extension folder into a .zip and places it in the server's deploy folder (or uploads it directly if you're working against an environment with the CLI configured). The portal detects the package, registers it, and the custom element becomes available to add to any page or fragment, without restarting the server and without going through OSGi at any point.

Workstation with a laptop showing code from a frontend project

When an OSGi module still makes sense

Client Extensions don't replace everything OSGi used to do, and treating them as the universal solution is the same mistake we used to make by putting all the logic into portlets. If you need a service that hooks into the portal's lifecycle, that listens to internal events, or that exposes complex business logic reusable from several places, an OSGi module is still the right piece. The sensible approach is to decide case by case: decoupled frontend with its own pipeline, client extension; domain logic that lives inside the portal, OSGi.

Stacked shipping containers, as a metaphor for packaging and deployment

Before writing your first client extension from scratch, check out the training-courses and satisfaction-survey examples in the official repositories. They already solve the folder structure, the build, and the packaging, saving you a whole first day of trial and error with the client-extension.yaml.

Tags:liferayreactclient extensionsdesarrollo webosgidxpcustom element

Portals and applications built to last for years. And someone to maintain them.

We build and maintain portals, intranets and applications. And we rescue existing ones: we update them, tidy them up and leave them maintainable.

See portals and development