Replacing custom JSPs with Client Extensions
Custom JSPs are the single biggest reason Liferay upgrades hurt. Every overridden JSP is tied to internals that can change between releases, so each upgrade means re-checking and often rewriting them. Client Extensions exist precisely to break that coupling, but swapping one for the other is not a find-and-replace. It is a migration that rewards a careful, incremental approach.
Why JSP overrides age badly
A JSP fragment override copies a core JSP and edits it. The moment Liferay changes that JSP upstream, your copy is frozen in time: you miss bug fixes, and the override may break outright. Multiply that across dozens of overrides and an upgrade becomes a multi-week archaeology project. The cost is not the JSP itself; it is carrying it forward forever.
Map each JSP to the right replacement
Different JSP customizations map to different Client Extension types. Identifying the category first prevents over-engineering:
| What the JSP did | Client Extension replacement |
|---|---|
| Tweaked styling or markup | CSS / theme CSS client extension |
| Added front-end behavior | Custom Element (JS) client extension |
| Rendered data from a service | Custom Element calling a headless API |
| Changed a global template | FreeMarker theme contributor or fragment |
Migrate one surface at a time
The safe path is incremental. Pick one isolated JSP, build the equivalent Client Extension, deploy it alongside the old override, and verify behavior before removing the JSP. A typical sequence:
- Inventory every JSP override and note what each one actually changes.
- Start with the lowest-risk, most isolated override.
- Build the Client Extension and expose any needed data through a headless API.
- Deploy both, compare output, then remove the JSP override.
- Repeat, leaving the riskiest shared templates for last.
What you gain
Once the overrides are gone, the next upgrade stops being an audit of frozen JSPs. The front-end code lives outside the portal runtime, deploys independently, and uses tooling your developers already know. The migration is real work, but it converts a recurring upgrade tax into a one-time investment, which is usually the easiest performance and maintainability case to justify.