The Bad News

Every developer dreads the moment: the framework you built your application on is being discontinued. That's exactly what happened to us when Vaadin announced the deprecation of Hilla.

Our system is a business application providing the following features:

• User registration and authentication
• Product search and browsing
• Online payment processing
• Multi-device support (web browsers and staffed/unstaffed business terminals)

The tech stack: Spring Boot 3.x on the backend, a Lit + TypeScript SPA on the frontend. Around 20 views, 30 components, and 20 dialogs — a modest but non-trivial codebase with real-world requirements like authentication, payments, and multi-device support.

What Hilla Gave Us

For those unfamiliar, Hilla was Vaadin's full-stack framework that bridged Spring Boot backends with Lit-based frontends. It provided:

• Hilla Endpoints — Type-safe RPC from TypeScript to Java. Annotate a Java method with @Endpoint, and a TypeScript client stub is generated automatically.
• Authentication helpers — @vaadin/hilla-frontend handled auth state, login utilities, and Spring Security integration.
• Client-side routing — @vaadin/router for SPA navigation with auth guards.
• Connection state detection — @vaadin/common-frontend provided online/offline awareness tied to endpoint calls.
• Build tooling — A Vite plugin that handled code generation, theme application, and output placement into Spring Boot resources.

The developer experience was genuinely good. Writing a Java method and immediately calling it from TypeScript with full type safety felt almost magical. It lowered the barrier for Spring Boot engineers to work on frontend code significantly.

Then, in 2024, Vaadin announced that Hilla (specifically the Lit-based full-stack integration) would no longer be maintained. A React-based Hilla was offered as an alternative, but rewriting our entire Lit component library was not an option.

The only path forward: replace everything Hilla provided with general-purpose open-source libraries.

The Problems We Already Had

The deprecation announcement was the trigger, but if we're being honest, Hilla had been causing technical headaches well before that.

Spring Security and Session Interference

Hilla extended Spring Security and Spring Session internals in non-standard ways. This made it effectively impossible to use standard session-sharing solutions like Spring Session + Redis out of the box.

To achieve horizontal scaling behind a load balancer, we had to resort to some aggressive workarounds:

• Reverse-engineering Vaadin's internal classes (security configuration, request utilities)
• Using Java Reflection to access private methods and extract the framework's internal path resolution logic
• Extending the standard CSRF token with custom fields to build a token-based authentication mechanism
• Implementing a frontend middleware that detected 401 responses and transparently re-authenticated using the custom token

// Accessing a framework-internal private method via reflection
private String applyUrlMapping(String path) {
    try {
        Method method = RequestUtil.class.getDeclaredMethod(
            "applyUrlMapping", String.class);
        method.setAccessible(true);
        return (String) method.invoke(requestUtil, path);
    } catch (Exception e) {
        return "/";
    }
}

// Frontend: transparent re-authentication on 401
const unauthorizedHandler = async (context, next) => {
    const response = await next(context);
    if (response.status === 401 && await store.reAuthenticate()) {
        location.reload();
    }
    return response;
};

This combination achieved sticky-session-free load balancing. But it was fragile — every Vaadin version upgrade risked breaking the reflection-based hacks, and the maintenance burden was significant.

Servlet Mapping Conflicts

The other pain point was Hilla's custom servlet mappings and internal redirects.

Hilla registered its own servlet mappings to handle frontend routing, with internal redirects that intercepted requests before they reached Spring's standard handler mappings. This interfered with Swagger UI's static resource serving and the ALB's (Application Load Balancer) path-based routing rules. Debugging 404 errors became an exercise in tracing request flow through multiple interception layers. Ultimately, we had to give up on serving API documentation (Swagger UI) for our external data API entirely.

These weren't temporary annoyances — they were structural problems inherent to running Hilla alongside standard Spring ecosystem tools. The deprecation was the catalyst, but the conviction that migration would eliminate this technical debt is what made us commit to a full rewrite.

Assessing the Damage

The first task in any framework migration is a dependency audit. You need to draw a clear line between "what the framework was doing for you" and "what you built yourself."

After a thorough review, we identified five areas requiring replacement:

1. API Client (Hilla Endpoints)

The largest blast radius by far. Nearly every view depended on Hilla Endpoints for data fetching and mutations.

// Before: Hilla Endpoints
import { SomeEndpoint } from "Frontend/generated/endpoints";
const details = await SomeEndpoint.getItemDetails(itemId);

We needed a code-generation solution that could produce typed TypeScript clients from our existing API definitions.

2. Authentication (@vaadin/hilla-frontend)

Hilla abstracted away the mechanics of authentication — CSRF token handling, auth state polling, login/logout flows. All of this was bundled in @vaadin/hilla-frontend and integrated seamlessly with Spring Security.

3. Routing (@vaadin/router)

Client-side routing for 20 views, including route guards for authenticated pages and role-based access.

4. Connection State Detection (@vaadin/common-frontend)

Offline detection that was tightly coupled to Hilla's endpoint call mechanism. With business terminals in the mix, graceful handling of network interruptions was a hard requirement.

5. Build Tooling (Hilla/Vite Integration)

Hilla wrapped Vite with its own plugins for endpoint code generation, theme processing, and placing build output into Spring Boot's static resources directory. We needed to reconstruct this pipeline from scratch.

What Survived

Not everything needed replacing, and this was the silver lining:

• Vaadin Web Components — <vaadin-grid>, <vaadin-text-field>, and friends work independently of Hilla. No migration needed.
• Lit — Our template engine. Framework-agnostic by nature.
• MobX — State management. We had adopted it independently of Hilla.

The fact that UI components and the template engine survived intact was huge. It meant the migration could focus almost entirely on "how data is accessed" and "how screens get navigated to," leaving the visual layer untouched.

Technology Selection

With the scope clear, we moved to selecting replacements.

Here is the reasoning behind each choice.

Why OpenAPI Generator

Our first instinct was to write fetch wrappers by hand. With 20+ endpoints, that idea lasted about five minutes. We weren't willing to give up type safety either.

Fortunately, we already had a separate set of REST APIs for external data provision, documented with SpringDoc. OpenAPI schemas were already part of our workflow. Extending the same annotation approach to our frontend-facing APIs would give us a ready-made foundation for client generation.

Generating a TypeScript client from that schema was the natural next step. We chose OpenAPI Generator's typescript-fetch generator, integrated as a Maven plugin so client code is regenerated on every build.

// After: OpenAPI Generator
import { api } from "@/api/api-client";
const details = await api.getItemDetails({ itemId });

The call syntax changes slightly — parameters become an object literal, which is OpenAPI Generator's convention — but type safety is preserved. Your IDE still catches mismatched types at development time.

Why fetch + Spring Security (No Auth Library)

We considered several frontend auth libraries but ultimately went with plain fetch calls against Spring Security endpoints. The reason was pragmatic: our auth flow was straightforward. Form-based login, RememberMe cookies, CSRF tokens — Spring Security handles all of this natively.

We did have to implement what Hilla had been hiding — fetching the CSRF token before login, managing authentication state, wiring up the auth context in MobX — but being free from Vaadin's non-standard extensions meant we could align with Spring Security's standard configuration patterns. The overall authentication flow became much easier to reason about.

Why universal-router

The routing library decision required the most deliberation. Our candidates:

• Vaadin Router — Still available as a standalone package post-Hilla, but its long-term maintenance was uncertain. We were trying to reduce Vaadin coupling, not maintain it.
• React Router / Vue Router — Framework-specific. Incompatible with our Lit + Web Components stack.
• universal-router — Framework-agnostic, lightweight, excellent TypeScript support.

The deciding factor was framework independence. Our Lit + Web Components architecture was intentionally decoupled from any specific framework. The router should follow the same philosophy.

As a bonus, universal-router's API was similar enough to @vaadin/router that route definitions could be migrated with minimal rewriting.

Why Custom Connection State Detection

The ConnectionState from @vaadin/common-frontend was tightly coupled to Hilla's endpoint mechanism. With Hilla Endpoints gone, it couldn't function as-is.

We could have relied on navigator.onLine and the browser's online/offline events, but that only detects local network connectivity — not whether the server is actually reachable. For business terminals that might have a LAN connection but lose internet access, this distinction matters.

We built a ConnectionStateService that derives connection state from actual API call results. If requests start failing with network errors, the state transitions to offline. When they succeed again, it transitions back. Simple, but grounded in reality rather than browser heuristics.

Migration Strategy — Layer by Layer

With technology choices locked in, the question became: in what order do we migrate 70+ TypeScript files?

The "big bang" approach — rewrite everything at once — was off the table. Too much risk, too hard to debug when things go wrong. Instead, we adopted a layered migration strategy.

Step 1: Services, Stores, and Helpers

The first wave targeted the infrastructure layer — everything that sits between the UI and the outside world:

• Replace the API client (Hilla Endpoints → OpenAPI Generator)
• Implement the authentication service
• Replace the routing foundation
• Implement connection state detection
• Migrate shared utilities

Critically, no UI components were touched in this step. The goal was to stabilize the foundation before building on top of it.

Checkpoint: npx tsc --noEmit

We used TypeScript's compiler as our Step 1 acceptance test. Running npx tsc --noEmit verifies that all types resolve, all imports exist, and all function signatures match — without actually building anything. When this produced zero errors, we had confidence that the API call signatures were correct and the dependency graph was intact.

Step 2: UI Components

With the infrastructure stable, we moved to views, components, and dialogs:

• Rewrite route definitions for universal-router
• Replace API calls in each view with the new client
• Wire up authentication guards
• Remove all Hilla-specific imports

Checkpoint: npm run build

The acceptance test for Step 2 was a full production build. Vite's build process plus TypeScript compilation with zero errors meant the migration was mechanically complete.

Step 3: Quality Review

The final step was a file-by-file comparison between the pre-migration and post-migration codebases. We categorized every difference into one of two buckets:

• Intentional changes — Different API call syntax, new routing API usage, restructured auth flow. Expected and correct.
• Needs fixing — Logic accidentally dropped during migration, edge cases not handled, subtle behavioral changes.

This review was tedious but invaluable. It caught several unintended behavioral changes that would have been production bugs. When you're making sweeping changes across dozens of files, it's easy to accidentally delete a null check or change the order of operations.

Why This Order Matters

The layered approach exists to isolate failure domains.

When Step 1 stabilizes the API client and auth infrastructure, Step 2 can focus purely on UI concerns. If a view doesn't render correctly after migration, you know the problem is in the view code — not in the underlying API client or auth service. Without this separation, debugging becomes a nightmare of "is this a plumbing issue or a UI issue?"

Series Roadmap

This series covers the full migration across five articles.

Starting from Part 2, we'll dive into the specific problems we encountered and how we solved them, with plenty of code examples. Framework migrations never go exactly as planned — that's precisely why they're worth documenting.