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

Modernizing legacy customizations without a rewrite

Modernizing legacy customizations without a rewrite

When a customization is years old, tied to a deprecated API, and fragile on every upgrade, the instinct is to start over. But a big-bang rewrite means a long branch, a frozen feature set, and a high-stakes cutover where everything has to work at once. Most of the time you can modernize incrementally instead: isolate the legacy code behind a boundary, replace it piece by piece, and ship continuously. The system never stops working while you improve it.

Inventory before you touch anything

You cannot modernize what you cannot see. Start by cataloguing each customization: what it does, which APIs it depends on, whether those APIs are deprecated, and how much business logic actually lives in it. Most legacy code splits into three buckets, and the bucket decides the strategy.

Legacy patternModern replacementApproach
JSP / theme override hooksClient Extensions (CSS, JS, FreeMarker)Replace surface by surface
Expando custom fieldsLiferay ObjectsMigrate data, then swap reads/writes
Hand-built REST servletsHeadless APIs / JAX-RS modulesFront with a stable contract first
Service hooks on core entitiesService wrappers / OSGi componentsWrap, then narrow scope
Hardcoded SQL findersService Builder dynamic queriesIntroduce a service seam
Each legacy pattern has a supported modern equivalent you can migrate toward incrementally.

Wrap the legacy code in a seam

The key technique is the strangler pattern: put a clean interface in front of the legacy implementation so callers no longer depend on its internals. Once everything goes through that seam, you can swap the implementation behind it without touching callers. This is what makes incremental migration safe.

Migrate in small, shippable steps

  1. Introduce the interface and route all current callers through it (no behavior change).
  2. Add the modern implementation behind the same interface, dark or feature-flagged.
  3. Move a slice of traffic or one consumer to the new path and verify it in production.
  4. Cut the remaining callers over once the new path is proven.
  5. Delete the legacy implementation and the flag once nothing references it.

Let upgrades drive the priority

You rarely have budget to modernize everything, so let pain set the order. The customizations that break on every Liferay upgrade, depend on removed APIs, or block a version you need to reach are the ones to tackle first. Code that is ugly but stable and upgrade-safe can wait. Modernization is a means to reduce risk and cost, not an end in itself.

Why incremental beats the rewrite

An incremental migration keeps value flowing the whole time: every step is independently testable, independently shippable, and independently reversible. If a slice misbehaves you roll back one small change instead of an entire release. The legacy system stays in production, paying its way, until the day its last caller is gone. That is almost always cheaper, safer, and faster to value than a rewrite that has to land all at once.

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