Liferay DXP upgrading classic theme to Client extension

Migrating traditional Liferay themes (WAR-based theme modules) to Client Extensions is a major milestone when updating your Liferay DXP footprint. Client extensions decouple your customizations from Liferay’s core runtime, eliminating OSGi dependency issues and enabling zero-downtime deployments.

Here is a practical guide to converting a legacy Liferay theme into a modern Theme CSS Client Extension.

With a theme CSS client extension, you can override the current theme’s CSS files (main.css and clay.css) to change the look and feel of a page.

The theme CSS client extension is available in https://github.com/liferay/liferay-portal/tree/master/workspaces/liferay-sample-workspace/client-extensions/liferay-sample-theme-css-1 for your reference.

Structure:

my-theme-client-extension/

├── client-extension.yaml

├── package.json

└── src/

    ├── css/

    │   ├── _custom.scss

    └── static/

        └── images/

Lets dive deeper to client-extension.yaml

client-extesnion.yaml

assemble:

    -   from: build/buildTheme/img

        into: static/img

    -   from: build/buildTheme/images

        into: static/images

    -   from: src/fonts

        into: static/fonts

    -   from: src/css/lib

        into: static/css/lib

liferay-sample-theme-css-1:

    clayRTLURL: css/clay_rtl.css

    clayURL: css/clay.css

    frontendTokenDefinitionJSON: src/frontend-token-definition.json

    mainRTLURL: css/main_rtl.css

    mainURL: css/main.css

    name: Liferay Sample Theme CSS 1

    type: themeCSS

Let's breakdown this.

1. The assemble Section

assemble:

    -   from: build/buildTheme/img

        into: static/img

    -   from: build/buildTheme/images

        into: static/images

The assemble block dictates how files are copied and packaged from your source directories into the final output structure of the client extension bundle.

These directives ensure that after building the theme CSS client extension, images needed by the CSS are included as static resources in Liferay.

from: build/buildTheme/img ---> into: static/img

from: build/buildTheme/images ---> into: static/images

Copies compiled image assets from your build folder into the extension's static directory so they can be referenced by your CSS.

from: src/fonts ---> into: static/fonts

Bundles custom font files (like WOFF/WOFF2) used by your theme.

from: src/css/lib ---> into: static/css/lib

Copies third-party CSS files or style libraries into the final package path.

2. The Client Extension Definition Section (liferay-sample-theme-css-1)

type: themeCSS: Specifies that this client extension is a CSS-based theme extension (rather than a Custom Element, Global JS, etc.).

name: Liferay Sample Theme CSS 1: The user-friendly display name that appears inside the Liferay DXP UI (under Site Pages $\rightarrow$ Look and Feel).

clayURL & clayRTLURL:

clayURL: css/clay.css points to the main Clay CSS framework stylesheet (Left-to-Right layout).

clayRTLURL: css/clay_rtl.css points to the Right-to-Left language version for languages like Arabic or Hebrew.

mainURL & mainRTLURL:

mainURL: css/main.css points to your custom theme styling rules.

mainRTLURL: css/main_rtl.css points to your custom Right-to-Left styling rules.

frontendTokenDefinitionJSON: src/frontend-token-definition.json: Links your custom design tokens file. This enables content authors and administrators to modify variables (like colors, fonts, and spacing) dynamically using Liferay's built-in Style Books editor without needing a code deployment.

Note: Your code is present inside _custom.scss while the client-extension.yaml file points to clay.css and main.css. This is because the theme CSS client extension runs the full Clay CSS build process resulting in a compiled clay.css and main.css file that also contains the compiled CSS code from _custom.scss.