Low‑Impact Migration of Legacy Velocity Templates to a Modern Frontend Architecture

Velocity is a Java‑based web template engine that historically separated Java code from web pages, but many legacy systems still rely on it, causing maintenance difficulties for both backend and frontend developers.

To address these challenges, our team devised a low‑impact migration path consisting of four steps: (1) building a hybrid Velocity + MVC + MVVC architecture, (2) enabling single‑file componentization for Velocity, (3) creating a local Velocity sandbox with front‑end engineering support, and (4) achieving full front‑end‑back‑end separation of Velocity pages.

Step 1: Hybrid Architecture – We introduced the MVVC pattern using Vue and its UI library, allowing Vue components to coexist with existing Velocity templates. The rendering process now occurs in two stages: server‑side Velocity renders a Vue template, which the client‑side Vue engine then renders into the final page.

The hybrid architecture faces a challenge: some session parameters are generated server‑side and are not directly accessible to Vue, so placeholders are injected into the page and Vue reads them from the DOM at runtime.

Step 2: Velocity Single‑File Componentization – By leveraging Velocity’s #include and #parse directives together with Vue’s API, we created a .vm‑based single‑file component format that mirrors Vue’s .vue structure (template, script, style). Components are registered manually via Vue.component , enabling finer‑grained reuse across pages.

After componentization, Velocity pages can be assembled from smaller, reusable components, further reducing business coupling.

Step 3: Local Sandbox & Engineering – We built a sandbox that mocks server‑side variables and parses Velocity syntax in the browser using a custom velocity-loader for webpack, providing hot‑module replacement and millisecond‑level feedback for front‑end developers.

The sandbox transforms the development workflow into local real‑time editing with instant hot updates, dramatically improving developer experience.

Step 4: Full Front‑End Separation – The final step decouples Velocity pages from server rendering by converting dynamic data sections to Vue syntax and using Ajax for runtime data fetching, allowing independent front‑end builds and deployments.

Through this incremental approach, legacy Velocity applications can be modernized with minimal disruption while improving development efficiency and maintainability.