All posts
Liferay · 10 min read · Jun 16, 2026

Replacing custom JSPs with Client Extensions

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 didClient Extension replacement
Tweaked styling or markupCSS / theme CSS client extension
Added front-end behaviorCustom Element (JS) client extension
Rendered data from a serviceCustom Element calling a headless API
Changed a global templateFreeMarker theme contributor or fragment
Match the JSP's real responsibility to the lightest extension that covers it.

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:

  1. Inventory every JSP override and note what each one actually changes.
  2. Start with the lowest-risk, most isolated override.
  3. Build the Client Extension and expose any needed data through a headless API.
  4. Deploy both, compare output, then remove the JSP override.
  5. 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.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar