Durante años, cualquier pieza de interfaz en Liferay (un portlet, un widget, hasta un simple fragmento de JavaScript suelto) acababa empaquetada en un módulo OSGi. Funcionaba, pero el coste era alto: aprender el ciclo de vida de OSGi, lidiar con bnd.bnd, esperar a que el módulo resolviera sus dependencias y, muchas veces, pelear con versiones de librerías que el propio portal ya traía incluidas. Para un desarrollador frontend que viene de React, Vue o simplemente de JavaScript moderno, ese salto era una barrera real.
Las Client Extensions quitan esa barrera. Son la forma que tiene Liferay DXP (desde la versión 7.4) de desplegar código frontend sin tocar OSGi: un paquete declarativo, descrito en un fichero client-extension.yaml, que el portal registra y sirve como si fuera cualquier otro recurso estático. No hay contenedor OSGi de por medio, no hay que esperar a que un bundle arranque, y el ciclo de desarrollo se parece mucho más al de cualquier proyecto frontend actual: build, zip, despliegue.
Por qué Liferay apuesta por este modelo
El cambio tiene consecuencias prácticas. Separar el frontend del backend OSGi permite que un equipo de frontend trabaje con su stack habitual (React, Vue, webpack, Vite) sin necesidad de entender Java ni el ciclo de vida de los servicios de Liferay. Y permite algo igual de importante: que ese código se despliegue de forma independiente, con su propio pipeline, sin arrastrar una recompilación completa del portal.
En nuestro trabajo con Liferay DXP, esto se traduce en proyectos más fáciles de repartir: quien hace el frontend entrega su client extension, quien hace el backend sigue con sus módulos OSGi cuando realmente los necesita (lógica de negocio, servicios, integraciones), y ambos convergen en el mismo portal sin pisarse. Para una parte de ese scaffolding inicial, los ficheros de configuración y la estructura de carpetas, usamos agentes de IA que generan la base siguiendo las plantillas de Liferay; la revisión final de lo que se despliega la hace siempre una persona.
Los tipos de Client Extension que te vas a encontrar
No todas sirven para lo mismo. Liferay define varios tipos, y el error habitual es intentar forzar uno para un caso que pide otro:
- •customElement: el más usado. Registra un elemento HTML personalizado (un custom element del estándar web) que puede renderizar React, Vue o JavaScript vanilla. Es la vía natural para widgets interactivos que antes habrían sido un portlet.
- •themeCSS: inyecta hojas de estilo adicionales en el tema activo sin tener que recompilar ni desplegar un tema nuevo. Útil para ajustes de marca puntuales o para sobrescribir estilos de un componente concreto.
- •globalJS: carga un script JavaScript en todas las páginas del portal. Pensado para utilidades transversales (analítica, polyfills, pequeñas integraciones) que no necesitan interfaz propia.
- •oAuthApplication: registra una aplicación OAuth2 para que servicios externos (o el propio frontend) consuman las APIs headless de Liferay sin pasar por la autenticación clásica de sesión.
- •batch: encapsula procesos que se ejecutan de forma programada o bajo demanda, como importaciones masivas de datos, sin necesidad de un módulo OSGi con un scheduler propio.
En la práctica, el 80% del trabajo frontend en un proyecto Liferay actual pasa por customElement. Por eso merece un ejemplo completo.
Portales y aplicaciones que aguantan años. Y alguien que los mantiene.
Construimos y mantenemos portales, intranets y aplicaciones. Y rescatamos los que ya existen: los actualizamos, los ordenamos y los dejamos mantenibles.
Ver portales y desarrolloUn custom element en React, paso a paso
Vamos a montar un widget sencillo, un listado de cursos, siguiendo la misma estructura que usan los ejemplos oficiales de Liferay en sus repositorios de client-extensions (tanto en cis/client-extensions como en portal/client-extensions, donde encontramos casos ya resueltos como training-courses o satisfaction-survey). Son una referencia obligada antes de escribir una línea propia: resuelven de antemano dudas de empaquetado y de comunicación con el portal que, si no, se descubren a base de ensayo y error.
El fichero client-extension.yaml
Todo client extension arranca aquí. Este fichero describe qué se despliega y cómo se integra con el portal:
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: trueDos detalles importan de verdad. El bloque assemble indica qué carpeta de salida del build se empaqueta como recurso estático: si apuntas a la carpeta equivocada, el deploy no falla, pero el elemento no encuentra su JavaScript en tiempo de ejecución. Y htmlElementName es el nombre del custom element tal cual lo vas a usar en una página o fragmento: <training-courses></training-courses>.
El componente React
El punto de entrada registra el custom element en el navegador. No hace falta ningún framework de Liferay dentro del componente, solo la API estándar de customElements:
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);
}El componente TrainingCourses es React normal y corriente: puede llamar a las APIs headless de Liferay con fetch, pintar una lista, paginar. Si el custom element necesita autenticarse contra una API externa, lo hacemos con un oAuthApplication aparte, no mezclado con este mismo paquete.
Build y despliegue
El build es el de cualquier proyecto React con webpack o Vite, generando los artefactos en la carpeta build que el client-extension.yaml espera. El paso específico de Liferay es empaquetar y desplegar ese resultado junto al yaml:
npm run build
liferay-cli deployEl comando de despliegue empaqueta la carpeta del client extension en un .zip y lo coloca en la carpeta de deploy del servidor (o lo sube directamente si trabajas contra un entorno con la CLI configurada). El portal detecta el paquete, lo registra y el custom element queda disponible para añadirlo a cualquier página o fragmento, sin reiniciar el servidor y sin pasar por OSGi en ningún momento.
Cuándo sigue teniendo sentido un módulo OSGi
Las Client Extensions no sustituyen todo lo que hacía OSGi, y tratarlas como la solución universal es el mismo error que cometíamos antes al meter toda la lógica en portlets. Si necesitas un servicio que se engancha al ciclo de vida del portal, que escucha eventos internos o que expone una lógica de negocio compleja reutilizable desde varios sitios, un módulo OSGi sigue siendo la pieza correcta. Lo razonable es decidir caso por caso: frontend desacoplado y con su propio pipeline, client extension; lógica de dominio que vive dentro del portal, OSGi.
Antes de escribir tu primer client extension desde cero, revisa los ejemplos de training-courses y satisfaction-survey en los repositorios oficiales. Resuelven de partida la estructura de carpetas, el build y el empaquetado, y ahorran el primer día entero de prueba y error con el client-extension.yaml.
