Two migrations that both worked
On a Sunday in March 2022, Stripe converted the codebase behind the Stripe Dashboard from Flow, Meta's type checker for JavaScript, to TypeScript. In its engineering post, Stripe reports: "In a single pull request, we converted more than 3.7 million lines of code." The team locked its monorepo, the shared repository that holds the Dashboard code, that morning, took a final quality assurance (QA) pass over the branch and merged.
Twitch went the other way. Its account of breaking up its Ruby on Rails monolith describes a company-wide campaign, begun in 2015, "to move all of Twitch's backend code into Go microservices." A reverse proxy built on NGINX (an open-source web server) sent a share of traffic to a new application programming interface (API) edge written in Go, endpoint by endpoint. The work engaged backend engineers from 2016 to 2018. By the end of 2018 all traffic had left the monolith, and the post adds: "It would still take another year to fully clean up the account of dependencies and access roles."
Both teams finished. Neither account is a controlled comparison, and neither proves its strategy is better. Read together, they help explain each choice.
Fowler's warning is about rewrites
The incremental pattern takes its name from Martin Fowler's Strangler Fig Application entry, first published as "Strangler Application." The new system grows around the old one and takes over its behavior piece by piece. Fowler's case against the alternative is blunt. Teams plan to build a new system that does exactly what the old one does, "But we've seen this simple-sounding plan go down in flames most of the time."
That warning targets a rewrite: people re-implementing behavior nobody has fully specified, while users wait for features. Stripe did not rewrite anything. A codemod, a program that rewrites source code mechanically, translated the Flow code to TypeScript. Stripe spent several months extending a codemod Airtable had published until it handled the Dashboard's edge cases. It had also read accounts from Airtable and Zapier, which had each run a converter over their whole codebase and "merged the output as a single commit." The big-bang step was a machine translation, checked by tests and manual QA.
Fowler names the price of his own pattern too: transitional architecture, "code that will go away once the modernization is complete." He judges that "the reduced risk and earlier value from the gradual approach outweigh its costs." That judgment holds when coexistence is cheap. Stripe's post explains a case where it was not.
The four factors that decide it
Stripe's section on choosing a strategy gives its reasons in three sentences. "The Dashboard codebase has tight coupling between disparate components and no cleanly factored dependency graph." An incremental migration "would force developers to work in both languages to accomplish common tasks." And the team "would also need an interoperability layer to sync type definitions between both languages." Add the question of whether the target can run beside the source at all, and you have four factors:
| Factor | Points to big-bang | Points to strangler |
|---|---|---|
| Coupling | No clean seams; most changes touch many components (Stripe's Dashboard) | Separable units with their own traffic, such as endpoints (Twitch) |
| Tooling | A codemod or compiler can translate the whole codebase | The target needs new code written by people |
| Cost of coexistence | Developers would work in two languages and keep an interoperability layer in sync | A proxy or adapter keeps the two sides apart at low cost |
| Target compatibility | Old and new cannot run side by side without extra machinery: a file is checked by Flow or by TypeScript, not both | Old and new can each serve live traffic, with a proxy choosing between them |
The factors apply per boundary, not per company. Stripe itself handled one piece incrementally. Sail, its shared design system of React components, stayed in Flow while the team generated TypeScript definitions for it and wrote tests to keep the two in step. The post calls that approach "too cumbersome for a large codebase" and says it worked for Sail because "the Sail component interface is explicit and quite rigid." One interface with clean seams went incremental, and the tightly coupled application around it went all at once.
Grab's 2016 Rails to Go migration shows the same test from the other side. Its rollout write-up explains why it did not switch the Domain Name System (DNS) record for its public API to the new server in one step. The Go server would have had to be "coded, tested and configured with perfect foresight" to take all passenger app traffic across more than 30 endpoints at once. The endpoints were separable, so the team shadowed each one, sending copies of live requests to the Go server without returning its responses, and then moved them one by one.
Incremental is not always safer
A strangler migration spreads risk over time instead of removing it. Twitch's post lists what the long middle cost. Developers "had to write code in multiple repositories with different deploy cycles to deliver a single feature." After a 2017 mobile release overloaded the API, the team found that "no one had the responsibility to verify that the two parts worked well together." Retiring the last monolith endpoints meant guessing who still called them: "The only way to tell if it was safe to shut them down was to force 10 minutes of downtime and see if anyone would complain."
Stripe concentrated its risk into one planned day, and the post does not pretend the day was safe: "we were mutating every file in the codebase." The Dashboard had limited end-to-end test coverage, so product teams ran manual tests, which caught a bug that stopped translations loading for non-English users.
Stripe paid in other ways too. Hundreds of engineers contribute to the Dashboard each week, so the team merged on a Sunday with the monorepo locked. It disabled some custom lint rules to restore later, and it accepted 37,000 TypeScript error suppressions, down from more than 97,000 on the first pass, against roughly 5,000 in the Flow code. Tests passed, and the team reports "no unpleasant surprises" as traffic shifted to the new code.
Neither strategy is the cautious one by default. A big-bang change that goes wrong does so on a known day, with the whole team watching. A strangler migration can go wrong quietly for years: a feature built in the wrong stack, a call that skips the adapter, an endpoint nobody owns. When a tool can do the translation and coupling makes coexistence expensive, the atomic change can carry less total risk.
What each choice leaves to govern
The two strategies produce different decisions to keep. A big-bang migration needs one decision after the switch: the old form does not come back. Stripe's suppressions are a known backlog, and the risk is new code that reintroduces the retired pattern, from a branch opened before the switch or an old example. A strangler migration needs a set of transitional decisions, each scoped to the paths it governs and each with a condition that retires it. ADRs for software migrations covers how architecture decision records (ADRs) carry legacy, target and transitional states. Strangler-fig migrations covers keeping new code from reaching past the compatibility adapter while the boundary moves.
The choice itself is a decision, and it rarely gets written down. Record which of the four factors you assessed and what you found. If coupling drove a big-bang choice, the next team can check whether the coupling still exists before it plans the next migration. Migrating from Node.js to Go works through the decisions that a language migration has to keep, including who authorizes each cutover. Coding agents change the tooling factor. Our reading is that cheaper translation pushes some migrations toward a single conversion, while AI-assisted migrations raise the drift risk on the incremental side, where agents copy whichever stack sits nearest.
Once the follow-on decisions are written down, something has to check new code against them. Mneme, an open-source decision and control layer for agentic software development, can enforce part of either outcome today. It enforces only decisions that carry an active typed rule, a machine-checkable constraint attached to the decision and switched on. A rule matches exact literal text, optionally limited to paths.
After a Flow to TypeScript switch, for example, a rule can forbid the @flow pragma (the comment at the top of a file that turns Flow checking on) under the converted application's paths. During a strangler migration, a rule can forbid the legacy package's import path in the new tree, with the adapter excluded.
When Claude Code, Codex CLI (OpenAI's command-line coding agent) or Kiro CLI 3.0 (the command-line version of Amazon's Kiro agent) edits a file through its own editing tools, Mneme checks the change before the file is saved. Continuous integration (CI) checks pull requests. Each result is PASS, WARN or FAIL, and a violation names the decision it broke. The Decision Index, Mneme's persisted, versioned record of decisions, keeps each decision's versions, lifecycle status and source. It does not record who approved a decision, so keep that approval in review.
Mneme does not choose the strategy, score coupling or prove that a converted codebase behaves like the original. Your tests, codemod and deployment tools answer those questions. Keeping the chosen strategy's decisions in force afterwards is part of engineering decision governance.
What engineering leaders should do
- Separate translation from rewriting. Fowler's warning is about people re-implementing behavior. A tool-driven conversion carries different risks, which you test for in QA and production monitoring.
- Price coexistence before you choose. Count the interoperability layers, the dual-language work and the years of transitional code, the way Stripe did.
- Decide per boundary. A rigid interface can migrate incrementally inside a codebase that moves all at once.
- Write the choice down with its factors, then write the follow-on decisions: no reintroduction after a big-bang switch, scoped transitional decisions with retirement conditions during a strangler migration.