liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/scaffold-client-extension
scaffold-client-extension
VerifiedGenerate 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
| Input | How to Obtain |
|---|---|
| Extension name | From user; convert to kebab-case for the directory |
| Workspace ID | Read from the id field at the root of client-extension.yaml in the workspace root |
| Microservice port | For microservice types; default 8081, or next unused port |
| OAuth scopes | Look 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'shtmlare stored, then stripped at render. The element's tag stays inert, with no error. Keep only the bare tag inhtmland inject the assets from the fragment'sjs, guarded by adata-*marker so a second placement does not load them twice. The paths are the yaml'surls/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
jsImportMapsEntryvariant when the configuration varies per placement orhtmlAttributesdoes not reach the tag: the fragment'sjsrunsimport('<bareSpecifier>'), the module callscustomElements.definewithobservedAttributes, and the fragmenthtmlsets those attributes from its configuration with?has_content, not!, because a value that was never configured is"". A Vite library build also needs theNODE_ENVdefine (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
| Symptom | Check |
|---|---|
| Bundle not STARTED | Read bundles/logs/liferay.<date>.log for the error; run diag <id> in Gogo shell |
| Custom element not in Fragments panel | htmlElementName must be a valid custom element name (contains a hyphen) |
| 401 from microservice CET | OAuth companion not deployed or scopes insufficient |
| Site initializer not in template list | CET not ACTIVE; redeploy and recheck log |
CET STARTED but its CSS/JS returns 404 | assemble 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 zip | An 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.cssis 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.cssmust be selfcontained. TheglobalCSSclient 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), nativefetch()omits the CSRF token and the request is rejected. - For GET calls on nonpublic Object APIs, native
fetch()sends an anonymous request — Liferay responds200 OKwithitems: []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
CustomEventwith{bubbles: true, composed: true}instead. - The callback receives the payload itself, with no
.detailenvelope. - 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |