[Deep Dive #38] Single-Pass Migration Bridges - discussion
Deep Dive #38 is pushing a decisive migration posture: adopt in a single pass to avoid split mental models, preserve URLs by importing legacy routes into the file router, and layer replacement UI via component routes while a bridge ledger tracks what is still legacy vs replaced.
If you have done a large migration, what made the bridge period survivable? Do you prefer a short, intense hybrid phase (single pass), or a longer incremental rollout with more parallel patterns? How do you keep the bridge ledger honest as teams replace pieces at different speeds?
Comments (10)
Back to latestThe strongest argument for single pass is the human side: one story, one router model, fewer footguns.
I like the preserve-URL-first posture. Once URLs are stable, you can iterate on the surface without breaking users.
Related: Migrating to React and Routing and Navigation.
We kept a literal ledger (in state) and rendered it in internal builds so nobody could pretend the bridge was done:
ts
type BridgeProgress = { shell: boolean; header: boolean; panel: boolean; footer: boolean };
const ledger = useLiveState('bridge-ledger', { replaced: { shell: true, header: true, panel: false, footer: false } });When you can see it, it is harder to drift into permanent hybrid.
Counterpoint: single pass is aspirational. In regulated products, you often cannot do one big cutover without extended parallel runs.
That is fair. I read single pass as: one adoption moment for the mental model, not necessarily one deploy for all surfaces.
You can still have phased rollout, but you try to avoid two competing routing languages at once.
That interpretation makes it more practical. The issue is when teams keep both models forever.
The component-route layering part is the most useful.
We replaced panels inside a legacy screen without touching the URL map at all, and it made the migration feel incremental even though the router story was unified.
Misunderstanding I had: I thought preserve URLs meant keep the legacy router alive.
Importing the map into file routes is the opposite: you make the new router authoritative immediately.
Exactly. You keep the address stable, not the implementation.
We put the ledger into PR review. If you replaced a component route, you also updated progress evidence.
It sounds bureaucratic, but it prevented the bridge from becoming a graveyard of half-migrated surfaces.
A tiny detail: normalize route map imports early.
We had two teams import the same legacy route with different casing rules and it caused bizarre redirects until we made it deterministic.
If you are going to do single pass, invest in audit tooling for the bridge period.
Without evidence, leadership starts asking why it is taking so long and engineers cannot answer coherently.
The ledger part is the key. The migration does not exist unless the route can prove where it is.