Skip to content

liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/scaffold-client-extension

scaffold-client-extension

Verified

Generate the directory structure and client-extension.yaml for any Liferay client extension type. Use when the user asks to create a client extension, scaffold a custom element, add an object action microservice, create a site initializer, or build any other CET. After scaffolding, calls deploy-and-verify to confirm startup.

Scaffold Client Extension

Generate a ready to deploy client extension under client-extensions/<name>. The CET type drives the file layout and the companion OAuth entry requirement.

When to Invoke

  • "Create a client extension", "scaffold a custom element", "build a React widget"
  • "Add an object action microservice"
  • "Create a site initializer"
  • "I need a global CSS override" or "inject a JS library on every page"

Workflow

Identify the CET Type

If the user did not specify a type, ask. Refer to rules/client-extension-types.md for the full list of types grouped by classification:

  • Frontend: customElement, globalCSS, globalJS, iframe, themeCSS, themeFavicon, themeSpritemap, staticContent, jsImportMapsEntry, editorConfigContributor, fdsCellRenderer, fdsFilter, commerceCheckoutStep
  • Microservice: objectAction, objectValidationRule, objectEntryManager, workflowAction, notificationType, captcha, commercePaymentIntegration, commerceShippingEngine, commerceTaxEngine
  • Configuration: oAuthApplicationHeadlessServer, oAuthApplicationUserAgent, instanceSettings
  • Batch: batch, siteInitializer

Collect Inputs

InputHow to Obtain
Extension nameFrom user; convert to kebab-case for the directory
Workspace IDRead from the id field at the root of client-extension.yaml in the workspace root
Microservice portFor microservice types; default 8081, or next unused port
OAuth scopesLook up in rules/oauth-scopes.md for the CET type

Create the Directory

client-extensions/<extension-name>/
  client-extension.yaml

Additional source files depend on type (see templates below).

Type Specific Templates

customElement (React example)

assemble:
  - from: <build-output-dir>
    into: static

<workspace-id>-<name>:
  cssURLs:
    - "css/main.css"
  friendlyURLMapping: <name>
  htmlElementName: <name>-element
  name: <Display Name>
  portletCategoryName: category.client-extensions
  type: customElement
  urls:
    - "js/main.js"
  useESM: true

Source layout:

client-extensions/<name>/
  client-extension.yaml
  package.json
  src/
    index.jsx       # React entry, exports a web component
  build.gradle      # optional; Blade transpiles via Liferay's frontend Gradle tooling

Minimal src/index.jsx:

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

class MyElement extends HTMLElement {
  connectedCallback() {
    const root = createRoot(this);
    root.render(<App />);
  }
}
customElements.define('<name>-element', MyElement);

function App() {
  return <div className="<name>">Hello from <Display Name></div>;
}
Placing It on a Page Through a Fragment

Verified on 2026.Q1:

  • <script src> and <link rel="stylesheet"> in a fragment's html are stored, then stripped at render. The element's tag stays inert, with no error. Keep only the bare tag in html and inject the assets from the fragment's js, guarded by a data-* marker so a second placement does not load them twice. The paths are the yaml's urls/cssURLs (see "Asset URLs").
  • A CET referenced as a fragment by its key ("fragment": {"key": "<cet-key>"}) vanishes from the tree and the render, silently.
  • Use the jsImportMapsEntry variant when the configuration varies per placement or htmlAttributes does not reach the tag: the fragment's js runs import('<bareSpecifier>'), the module calls customElements.define with observedAttributes, and the fragment html sets those attributes from its configuration with ?has_content, not !, because a value that was never configured is "". A Vite library build also needs the NODE_ENV define (react-custom-elements).
if (!document.head.querySelector('[data-<name>-assets]')) {
	const link = Object.assign(document.createElement('link'), {href: '/o/<friendlyURLMapping-or-key>/<css-url>', rel: 'stylesheet'});
	const script = Object.assign(document.createElement('script'), {src: '/o/<friendlyURLMapping-or-key>/<url>', type: 'module'});
	script.setAttribute('data-<name>-assets', '');
	document.head.append(script, link);
}

globalCSS

assemble:
  - from: css
    into: static

<workspace-id>-global-css:
  name: <Display Name> Global CSS
  scope: company
  type: globalCSS
  url: "main.css"

scope: company injects it on every page. Without it the file is served but never injected; bind it per master instead when it belongs to one site (rules/client-extension-types.md). The same assemble/scope rules apply to globalJS below.

client-extensions/<name>/
  client-extension.yaml
  css/
    main.css

globalJS

assemble:
  - from: js
    into: static

<workspace-id>-global-js:
  name: <Display Name> Global JS
  scope: company
  scriptElementAttributes:
    async: true
  type: globalJS
  url: "main.js"

Keep DOM listeners out of a globalJS file. Its script tag carries data-senna-track="temporary", so Senna executes it again on every navigation in the browser with document.readyState already complete. An init that waits for DOMContentLoaded then never fires, querySelector finds nothing, and the feature silently does nothing. Put reusable logic (fetches, data shaping) in the CET. Attach listeners in the fragment's own index.js, which runs right after that instance's markup with fragmentElement bound. If a global script must touch the DOM, initialize at once when document.readyState !== "loading", and wait for DOMContentLoaded only otherwise. Verified on 2026.Q3.

objectAction (Spring Boot example)

<workspace-id>-oauth:
    .serviceAddress: localhost:8081
    .serviceScheme: http
    name: <WorkspaceId> OAuth
    scopes:
        - c_<name>.everything
    type: oAuthApplicationUserAgent

<workspace-id>-<name>:
    name: <Display Name> Action
    oAuth2ApplicationExternalReferenceCode: <workspace-id>-oauth
    resourcePath: /object/action/<name>
    type: objectAction
client-extensions/<name>/
  client-extension.yaml
  Dockerfile        # Required, see below
  LCP.json          # Required, see below
  src/main/java/<package>/
    Application.java
    ObjectActionRestController.java
  src/main/resources/
    application.properties

ObjectActionRestController.java minimal shape:

@RestController
public class ObjectActionRestController {

    @PostMapping("/")
    public ResponseEntity<String> post(@RequestBody Map<String, Object> body) {

        // Body contains the object entry fields

        return ResponseEntity.ok("{}");
    }

}

application.properties:

server.port=8081
liferay.oauth.application.external.reference.code=<workspace-id>-oauth

Every Microservice Project Needs a Dockerfile and LCP.json

The project templates above list only source files, but createClientExtensionConfig refuses a microservice project without both, even for a purely local deploy:

Required file "Dockerfile" not found in project "<name>"
Required file "LCP.json" not found in project "<name>"

Copy them from the matching sample on GitHub — liferay-sample-etc-node or liferay-sample-etc-spring-boot — and change the port in LCP.json to the one in .serviceAddress. Verified on 2026.Q1 with a Node project.

This holds for every microservice type: objectAction, objectValidationRule, objectEntryManager, workflowAction, and the rest. The workspace plugin carries default templates only for the batch, configuration, and frontend classifications, so nothing fills them in. Verified on 2026.Q3.

Run a Microservice Locally

Deploying registers the CET with Liferay; it does not start the service. dockerDeploy runs after deploy and reports BUILD SUCCESSFUL even when Docker is not running, so a successful build is no sign the service is up (verified on 2026.Q3). The deploy writes the service's configuration into bundles/routes/default/<project> and the portal's into bundles/routes/default/dxp. Point the service's config loader at both, as the samples do.

Start the service detached from the agent's session. It has to keep running after the agent finishes or goes down — object actions keep firing at it, and anything that fires while it is down fails and is not retried. An agent's own background execution ties the process to the session, so it dies with it. Start it in a new session with setsid nohup, logging to the bundle's log directory (for Node, after npm install in the project):

WORKSPACE=$(pwd)

setsid \
	nohup \
	env \
	LIFERAY_ROUTES_CLIENT_EXTENSION="${WORKSPACE}/bundles/routes/default/<project>" \
	LIFERAY_ROUTES_DXP="${WORKSPACE}/bundles/routes/default/dxp" \
	node \
	"${WORKSPACE}/client-extensions/<project>/app.js" \
	> "${WORKSPACE}/bundles/logs/<project>.log" 2>&1 < /dev/null &

Run it from the workspace root. Stop an earlier copy first — a second one fails to bind the port and exits, leaving the old code serving:

WORKSPACE=$(pwd)

pkill -f "[n]ode ${WORKSPACE}/client-extensions/<project>/app.js"

The [n] keeps the pattern from matching the shell that runs the command. Without it, pkill also kills that shell, because its own command line contains the pattern.

Then confirm both that it answers and that it no longer belongs to the agent. Run this from the workspace root too:

WORKSPACE=$(pwd)

curl \
	--silent \
	--url "http://localhost:<port>/ready"

ps -o pid=,ppid=,sid=,args= -p "$(pgrep -d , -f "[n]ode ${WORKSPACE}/client-extensions/<project>/app.js")"

READY means it is up. ps prints one line per copy; more than one line means an earlier copy is still running. The process must be its own session leader — its pid equals its sid — and its parent must not be the agent's process. If either check fails, the service stops when the session does. It does not survive a reboot; restart it the same way after one.

siteInitializer

<workspace-id>-site-init:
  name: <Site Name> Initializer
  oAuthApplicationHeadlessServer: <workspace-id>-site-oauth
  siteExternalReferenceCode: <site-erc>
  siteName: <Site Name>
  type: siteInitializer

<workspace-id>-site-oauth:
  name: <Site Name> OAuth
  scopes:
    - Liferay.Headless.Site.everything
  type: oAuthApplicationHeadlessServer

Populate site-initializer per rules/site-initializer-format.md.

siteExternalReferenceCode uniquely identifies the site so rerunning the initializer updates it rather than creating a duplicate. Derive it from the site name in kebab case.

batch

Copy liferay-sample-batch from GitHub into client-extensions/<name>. Rename the top level keys and each name in client-extension.yaml, and replace the files in batch with your own.

Keep the sample's assemble block. Without it, the batch directory is left out of the zip. The build succeeds, the bundle reaches STARTED, and nothing is imported. The signal is assembleClientExtension NO-SOURCE in the build output, or no Started batch engine import task line in the log after STARTED. Confirm the files made it in with unzip -l dist/<name>.zip. Verified on 2026.Q1.

Files import in filename order, so number them so that dependencies come first. Each file is one envelope, in the shape of the sample's files. On a local bundle, the import runs inside the portal, and Liferay.Headless.Batch.Engine.everything alone was enough for ObjectField and ObjectAction items. Verified on 2026.Q1. Liferay Cloud was not tested.

A batch project needs no Dockerfile or LCP.json; the build and import succeed without them, as in the sample. Only microservice projects require them. Verified on 2026.Q1.

Wire OAuth When Required

If rules/client-extension-types.md shows "Yes" in the OAuth column, call setup-oauth to add the companion OAuth entry: oAuthApplicationUserAgent for a microservice CET, or oAuthApplicationHeadlessServer for a batch or siteInitializer CET (see rules/oauth-scopes.md). The OAuth entry must appear in the same client-extension.yaml file.

Deploy and Verify

Call deploy-and-verify. For microservice CETs, also start the microservice process on the declared port before the smoke check.

Troubleshoot

SymptomCheck
Bundle not STARTEDRead bundles/logs/liferay.<date>.log for the error; run diag <id> in Gogo shell
Custom element not in Fragments panelhtmlElementName must be a valid custom element name (contains a hyphen)
401 from microservice CETOAuth companion not deployed or scopes insufficient
Site initializer not in template listCET not ACTIVE; redeploy and recheck log
CET STARTED but its CSS/JS returns 404assemble missing or not copying the build output into static (see react-custom-elements)
createClientExtensionConfig FAILED — Required file "Dockerfile" / "LCP.json"Microservice CET without its own Dockerfile or LCP.json (see "Every Microservice Project Needs a Dockerfile and LCP.json")
type: batch CET deploys, but the batch directory is absent from the zipAn assemble block that is missing, or nested under the CET's key, reports NO-SOURCE silently; make it a top level key (see batch above)

CSS Architecture for Custom Elements

CSS rules in Custom Element CETs run alongside theme styles and other CETs. A few rules keep the cascade predictable:

  • global.css is additive only. Never redefine a class that already exists in the theme SCSS — the later stylesheet wins at equal specificity, producing silent cascade conflicts. Only add new classes.
  • Each component's style.css must be selfcontained. The globalCSS client extension is not injected on every site; never rely on it from inside a Custom Element. Every rule the component needs has to be present in its own stylesheet.
  • Prefix scoped selectors with the custom element tag name. E.g. my-widget .btn { ... }. This raises specificity above theme defaults regardless of stylesheet load order.
  • Include all required properties on each scoped rule. A scoped rule does not inherit sibling properties from a lower specificity theme rule — declare every property the component depends on.

Asset URLs

After deploy, CET assets are served at /o/<webContextPath>/<filename>.<hash>.<ext>. The exact URL — including the content hash — is regenerated on each build, so read the deployed *.client-extension-config.json (under bundles/osgi/client-extensions) to resolve it at runtime. Never hardcode asset paths.

Runtime Patterns When Calling Liferay APIs From a Custom Element

Always Use Liferay.Util.fetch

Use Liferay.Util.fetch for every API call inside a Custom Element — including GET requests:

Liferay.Util.fetch(endpoint, options)

Native fetch() fails in two distinct ways:

  • For write calls (POST, PUT, DELETE), native fetch() omits the CSRF token and the request is rejected.
  • For GET calls on nonpublic Object APIs, native fetch() sends an anonymous request — Liferay responds 200 OK with items: [] rather than a 401, silently hiding every record the Guest role cannot see.

Liferay.Util.fetch propagates the user's session context for both cases.

Resolve the Current User via my-user-account, Not ThemeDisplay

Never use Liferay.ThemeDisplay.getUserId() in Custom Element code that runs on the client. It can return 0 or a stale ID when the page is partially cached.

Resolve the current user via the session fresh API instead:

GET /o/headless-admin-user/v1.0/my-user-account

Call this through Liferay.Util.fetch so the CSRF token is attached automatically.

Messaging Between Widgets: Liferay.fire / Liferay.on

Liferay.fire(name, payload) and Liferay.on(name, callback) ship with the core JS, loaded in the <head> of every page before any fragment, so they need no CET and no import map. Verified on 2026.Q3:

  • Use them between two separately placed widgets with no DOM relation. A widget reporting its own state change to its ancestors dispatches a CustomEvent with {bubbles: true, composed: true} instead.
  • The callback receives the payload itself, with no .detail envelope.
  • The namespace is shared across the page. Give each event a specific name (<project>:<widget>:<event>).
  • Nothing is replayed or buffered. An event fired before Liferay.on() is lost, as designed, so the subscriber renders a coherent initial state without waiting for a message.
  • The subscriber updates its own element's attributes rather than implementing the emitter's logic again, and the emitter does not fire again for a state that has not changed.

Never Use roleBriefs for Access Control

my-user-account.roleBriefs is not invalidated immediately after a role is assigned via API — the permission cache may not reflect the new role until the session is refreshed or the cache expires.

Do not gate Custom Element UI on roleBriefs. Use a functional data check against your own object model instead — to confirm a user has a role, check whether they have records that prove it (a direct report, an account membership, an assignment). This is authoritative, always current, and degrades gracefully if the data model changes.

Success Signal

TODO / inferred — verify against a running bundle. Confirm the deployed CET manifests for its type via deploy-and-verify's Smoke Check on a live bundle.

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall