Contents
Switch frontend frameworks at URL boundaries, running only one framework per page load. Separate development of replacement screens from the changes that expose them to users, and ensure every release has a clear rollback procedure.
Key Points#
- Run one framework per document, and use full-page navigation between old and new route groups.
- Merge replacement screens into main before enabling them for users.
- Keep URLs, API contracts, and persistent data compatible so both implementations can work.
- Require existing end-to-end tests to pass with the same actions and expected results, and agree on behavior changes before implementation.
Choose the Boundary#
This approach suits browser-rendered single-page applications whose host returns the same HTML entry point for every application route. Both implementations must work with the existing backend. For server-rendered applications, make routing decisions on the server. The browser entry code below is not sufficient on its own.
Choose route groups where full-page loads are acceptable, such as public pages and an authenticated dashboard, or customer-facing pages and an admin interface. Keep frequent interactions within a single group. Crossing the boundary loses in-memory state, so address unsaved forms before introducing it.
Even when individual screens are implemented separately, the migration proceeds incrementally by route group. While developing the replacement dashboard, you can keep the entire existing dashboard in React. If work stalls, users can continue using the active implementation, but maintaining two codebases still takes time.
Start Only One Framework#
At the browser entry point, select the implementation once, before either framework starts. For example, you can use Foldkit for public pages while continuing to use React for /dashboard and its descendants.
const isDashboard = (path: string) =>
path === "/dashboard" || path.startsWith("/dashboard/");
const start = isDashboard(window.location.pathname)
? () => import("./dashboard-react/entry")
: () => import("./public-foldkit/entry");
void start().catch(showStartupError);Each entry module starts its respective framework. Use full-page navigation for links that cross the boundary, and client-side routing within each implementation. Test navigation in both directions, direct access, and the browser’s Back button. Include /dashboardx in routing tests to confirm that it does not match /dashboard/.
Dynamic imports allow the bundler to split the entry code. However, inspect the production build output and network requests before claiming that the unused framework is never downloaded. Shared imports, preload settings, and build configuration can affect the result. Startup failures also need a visible error message and a recovery action.
Separate Development from Release#
Move each route group through four stages.
1. Prepare: Record current behavior, bundle size, and existing end-to-end test results, and agree on intentional differences. 2. Develop: Merge replacement screens in small pull requests while keeping the active entry point launching the old implementation. 3. Switch: Enable the replacement through a separate entry-point change, and run the same acceptance checks. 4. Remove: After an agreed observation period, remove the old implementation and its dependencies.
Keep review units small enough to understand. The referenced taimei migration plan used 22 issues and a target of no more than 10 files per pull request. These are planning examples, not proof of safety. Nor does each completed issue represent the same amount of work.
Until the old implementation is removed, ensure that restoring the previous entry selection and deploying it is enough to roll back. Test that procedure and measure how long it takes. A small switching diff limits the changes made at release time, but cannot guarantee that the replacement screens are free of defects.
Make Compatibility Measurable#
Preserve the actions and assertions in existing end-to-end tests. Markup changes may require locator changes, but weakening assertions to make the migration pass removes evidence that behavior has been preserved. Record intended differences before coding, and treat undocumented differences as defects.
Explicitly check these four areas.
- Existing URLs, deep links, and handling of unknown routes.
- Authentication, authorization, and API request compatibility.
- Shared styles, keyboard interactions, and accessibility behavior.
- Production JavaScript size and the time required for critical user flows.
Rollback also requires data compatibility. If the new frontend writes a storage format that the old frontend cannot read, restoring the entry point alone is insufficient. Keep persistence formats compatible or provide a tested conversion method. Matching CSS classes alone does not prove visual or accessibility equivalence.
Add Flags as Needed#
Feature flags help with rollouts by customer group and rollbacks without deployment. Use a cookie or a server response generated appropriately for the user, and read it before either framework starts. If the value is missing or invalid, select the existing implementation. A browser-readable flag controls presentation; server-side authorization must remain independent.
Define exactly when a rollback takes effect. Changing the server-side rollout list does not update tabs that are already running. If a cookie is updated through /api/me after startup, the updated selection applies only on the next document load. Immediate recovery requires an explicit update or reload mechanism, and distributed flag storage may introduce propagation delays.
Run end-to-end tests with both flag values. Avoid embedding customer-specific flags in HTML stored in shared caches, and remove the flag along with the old code once rollback support ends. If you need to switch within a single screen, reconsider the boundary. That requires the integration work this approach deliberately avoids.
Next Steps#
Choose one low-risk route group and create a release checklist. Include the user flows to preserve, acceptable differences, data compatibility, and a rollback procedure with a measured recovery time.
Source: https://zenn.dev/yasuakiomokawa/articles/de83bb4c4ea928
Contents
