Working with Client Extensions
Using client extensions, you can extend Liferay without deploying OSGi modules. Just like traditional module development, client extensions live in a Liferay Workspace. Get started by learning
- What tools are required to begin developing client extensions
- How to define a client extension in its configuration file
- How to deploy client extensions
Required Tools and Settings
To start developing client extensions, obtain the following items:
Java 8 or JDK 11.note
Check the compatibility matrix for information on supported JDKs, databases, and environments. See JVM Configuration for recommended JVM settings.
A Liferay workspace. To download a workspace with example client extension projects, run
curl -o com.liferay.sample.workspace-latest.zip https://repository.liferay.com/nexus/service/local/artifact/maven/content\?r\=liferay-public-releases\&g\=com.liferay.workspace\&a\=com.liferay.sample.workspace\&\v\=LATEST\&p\=zip
You can copy the client extension projects (in the
client-extensions/directory) into your own workspace or use the sample workspace directly.
If you are using Liferay Experience Cloud(LXC), you must have the
Configuring Client Extensions
Client extensions are defined in
client-extension.yaml files containing these properties:
name: Enter the name as it appears in the Liferay UI. If it’s not configurable in the UI, the name value is not used.
type: Set the client extension’s type (e.g.,
globalCSS). The type determines how Liferay handles the client extension when it is deployed.
dxp.lxc.liferay.com.virtualInstanceId: Enter the ID of the virtual instance to deploy to.
Each client extension project lives in a folder inside of the workspace’s
client-extensions/ folder. The project contains a single
client-extension.yaml file, which defines one or more client extensions. For example, the
client-extension.yaml defines three
iframe client extensions:
Additional Source Files
The client extension’s source files are in the project’s
src/ folder by default. You can specify additional files to include in the built archive using an
assemble block in the
assemble: - from: assets include: "**/*" into: static
The assemble block has these properties:
from: Set a folder in your client extension project that houses the additional resources. When you build the client extension, these resources are included in the
.zip file. You can use multiple
from definitions in the
assemble block, with each containing an
include: Enter a single file or glob syntax to find the desired files in the
into: Specify where to include the additional resources in the built
static directory so that Liferay can serve them as static resources for your site.
Deploying to Your Liferay Instance
Client extensions are built into deployable
.zip archives. Each client extension archive contains a JSON file with the client extension’s settings.
Deploy client extensions by placing the
.zip files in the correct location for your Liferay installation. The exact commands you’ll use depend on how your Liferay instance is hosted.
Deploying to LXC
To deploy client extensions for LXC,
Go to your workspace’s
client-extensions/folder and run
../gradlew clean build
.zipfiles are created in each project’s
dist/folder. To build one project at a time, run the command from the project’s folder.
Run this command to deploy each client extension to your chosen environment:
lcp deploy --extension <extension-zip-file>
When prompted, select a project and the deployment environment. The zip files are uploaded to your LXC project once the command completes.
Deploying to a Self-Hosted Liferay Instance
If you host your Liferay installation on-premises, use the workspace bundle zip to deploy your client extensions. To build and deploy your client extensions, run this command from your workspace’s
../gradlew clean distBundleZip
If you must manually deploy the zip files, run
../gradlew clean build
Then copy the archives from each project’s
dist/ folder into the server’s
[Liferay Home]/osgi/client-extensions/ folder.