Home/Field Guide/Client extensions & APIs
CONCEPT 14
Client extension architecture
Package frontend, configuration, batch, and microservice extensions and understand their runtime boundaries.
What gets deployed
A client extension is a typed integration with Liferay. Workspace reads client-extension.yaml and packages the descriptor and assembled assets. The type determines how Liferay uses the artifact. A frontend custom element runs in the browser, while a microservice implementation runs in a separate process. Configuration and batch extensions express deployable settings or data. A ZIP that registers a service URL does not necessarily deploy or start that service.
| Category | Use it for | Check |
|---|---|---|
| Frontend | Custom elements, supported CSS/JS, theme resources, or editor and data-set extensions | Load scope, ordering, CSP, and target type support |
| Microservice | Supported event handlers or integrations running outside the JVM | URL routing, authorization, timeouts, and hosting model |
| Configuration | Supported OAuth and platform configuration as code | Stable identifiers, environment values, and secret injection |
| Batch | Promote supported artifacts or data with a repeatable package | Dependencies, replay, and supported entity types |
A practical deployment loop
- Scaffold from a sample that targets your release and type.
- Define a stable extension ID, declare its type and required properties, and assemble only the assets it needs.
- Build the client extension and inspect the archive contents. Deploy with the mechanism supported by the environment.
- Confirm registration in the UI or logs, then verify the behavior through the actual page or trigger.
- Rehearse rollback. Keep the previous artifact and account for data or configuration changes separately.
Typical failure modes
If the extension registers but assets return 404, inspect the assembled files and case-sensitive paths. If JavaScript downloads but the widget is blank, match htmlElementName to the registered tag and inspect console errors. If an Object action cannot reach a service, check deployment and DNS from the calling environment, then validate token policy and the service response. A single extension can be healthy while its dependency is unavailable.