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 pattern | Modern replacement | Approach |
|---|---|---|
| JSP / theme override hooks | Client Extensions (CSS, JS, FreeMarker) | Replace surface by surface |
| Expando custom fields | Liferay Objects | Migrate data, then swap reads/writes |
| Hand-built REST servlets | Headless APIs / JAX-RS modules | Front with a stable contract first |
| Service hooks on core entities | Service wrappers / OSGi components | Wrap, then narrow scope |
| Hardcoded SQL finders | Service Builder dynamic queries | Introduce a service seam |
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
- Introduce the interface and route all current callers through it (no behavior change).
- Add the modern implementation behind the same interface, dark or feature-flagged.
- Move a slice of traffic or one consumer to the new path and verify it in production.
- Cut the remaining callers over once the new path is proven.
- 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.