One company, one decade, two opposite policies. On the runtime it can change, Shopify has not migrated once since 2014; it bought the constraint and made it faster. On the runtime it cannot change, its storefront framework has moved foundations three times in five years. This guide reconstructs both from the repository record and extracts the test that separates them, so an architect can decide which of the two situations they are in before they choose between evolving a system and replacing it.
The problem, stated without naming a language: when a system you cannot leave is too slow or too tangled, do you improve it or escape it? Shopify has answered that question in public, in both directions, for ten years.
Every large engineering organisation eventually faces the same fork. A shared substrate, usually a language runtime and a framework, is holding the product back. The obvious moves are to escape it, by splitting the system into services that can each pick their own stack, or to endure it. Shopify took a third option on the backend and has held it for a decade: keep one codebase, keep one language, and spend the money on the substrate itself. The repository record shows what that cost and what it bought.
It also shows the counter-example, inside the same company and the same decade. Shopify's headless storefront stack has been rebuilt on three different foundations since 2021. Between the first and the second it went so far as to acquire the team behind the framework it adopted, and the churn continued anyway. Comparing the two arcs is the point of this guide, because the difference between them is not maturity or taste. It is leverage: on the backend Shopify can change the thing it depends on, and on the storefront it cannot.
The finding that was not expected. In January 2026 Shopify archived Ruvy, its attempt to run Ruby inside the WebAssembly sandbox it gives merchants, with a plain statement in the README: Ruvy is "not currently compatible with Shopify Functions" because the modules it produces exceed "the maximum size of Wasm modules supported by Shopify Functions". The company that spent the decade making Ruby fast enough to keep could not fit Ruby inside the extension platform it built for everyone else. A sandbox is not a smaller copy of your runtime. It is a different runtime with a different admission rule, and your own language has to apply like everyone else.
What this guide covers. The public repository record of Shopify and the projects it
funds, between 2014 and September 2026: resiliency libraries, the modularisation tooling,
the Ruby JIT work, the database driver change, the Kubernetes deploy tooling, the
WebAssembly extension toolchain, and the storefront framework lineage. What it
deliberately does not cover: anything Shopify never published. The shard router, the pod
topology, the Storefront Renderer, the data platform and the peak-traffic figures are all
absent, and so is every Shopify engineering blog post, conference talk and incident report,
because this session's network policy reached github.com and nothing else. That
limit is stated in full in the evidence wall, and it shapes what can
honestly be claimed here: this is the record of what was open sourced, which is a biased
sample of what was built.
Before choosing between improving a dependency and replacing it, answer one question: can you ship a change to it? Not "could we fork it", but can a person on your payroll land a change in the artefact everyone else consumes, on a schedule you influence. If yes, improvement is usually cheaper than escape, and it compounds. If no, you are a tenant, and a tenant should keep the wrapper thin and budget for moving house.
The shape that emerges from sixteen repositories: one codebase, partitioned by tenant rather than by function, with the boundaries enforced at build time and the failure containment sitting inside the process.
The conventional reading of a large commerce platform is a service mesh with a dozen domains behind it. The artefacts do not describe that system. They describe a single Rails application, partitioned horizontally so that a tenant lives on a shard, with four mechanisms bolted to it that would ordinarily be provided by a network: a static boundary checker instead of service interfaces, in-process bulkheads instead of a sidecar, an opt-in blob cache instead of a read-path service, and a WebAssembly sandbox instead of a plugin API.
The clearest evidence for the tenant partitioning is in an unglamorous place. Shopify's job-iteration gem, in production since May 2017, exists to make background jobs interruptible and resumable, and the README gives the reason in one sentence: "At Shopify, we also use it to interrupt workloads safely when moving tenants between shards and move shards between regions." A company only builds a checkpointing job framework if moving a tenant between shards is a routine operation. The unit of isolation is the shop, not the service.
Boundaries inside the code are enforced by Packwerk,
which groups files into packages, gives each package a public surface, and fails a check
when one package reaches into another's internals. The decisive design choice is not the
checker, it is the todo file: existing violations are written into
package_todo.yml and, in the words of the usage document, "worked off over
time" rather than blocking. That converts modularisation from a migration into a ratchet,
which is the only form in which a live monolith can accept it. The cost is a build-time one,
and it is real: checking the whole monolith took three and a half minutes until an outside
contributor added content-addressed caching in 2022 and brought it under twenty seconds.
Failure containment sits inside the worker process. Semian has been in production since October 2014 and does two things: it trips a circuit breaker when a resource starts failing, and it limits how many workers on a host may wait on that resource at once. In a services architecture, both of those usually live in a sidecar or a mesh. Putting them in the process costs nothing per request and requires no extra hop, and it only works because the unit of concurrency is a worker process with many siblings on the same host. Its sibling tool, Toxiproxy, has been in every development and test environment since the same month, which is the part most organisations skip: the containment is exercised on laptops, not only in a game day.
Reads are served through IdentityCache,
a blob cache that is explicitly opt-in and explicitly lossy. The README does not claim
correctness; it states the budget: "IdentityCache is never going to be 100% consistent,
since cache invalidations can be lost", then lists the ways they are lost, from a write that
skips an after_commit callback to a process dying between the database commit
and the invalidation. Naming your own inconsistency in the README is a design decision, and
a better one than an unstated guarantee that operators will assume is total.
Merchant code does not run in that process at all. It is compiled to WebAssembly, and the toolchain for that, Javy, now sits under the Bytecode Alliance rather than in Shopify's own organisation. Its README quantifies the constraint that matters: modules in "the 1 to 16 KB range with use of dynamic linking", against "at least 869 KB" when linked statically. A platform that runs untrusted extensions on every request is buying cold-start time in kilobytes, which is why the language admission rule is a size rule, and why Ruby did not pass it.
Shards hold shops, and shops move between shards as a routine operation. The job framework is built around that fact rather than around throughput.
Stated at: job-iteration
Violations are recorded and paid down. A checker that blocks on day one gets turned off on day two, which is the failure mode this design avoids.
Stated at: packwerk USAGE.md
Krane exists because kubectl apply "leaves its users with some burning
questions: What just happened? Did it work?" It adds a verdict, not a platform.
Stated at: krane
Six forks where the repository record shows both the road taken and the reason, plus the condition that would flip each one.
The most expensive decision in the set is also the least visible, because its artefact is not a Shopify repository at all. Shopify's response to Ruby being slow was to fund a JIT compiler inside CRuby. YJIT began in a Shopify repository, which now carries a one-line epitaph, "YJIT has been merged upstream, and is now an official part of Ruby 3.1+", and the work moved into the language. By the Ruby 3.2 release notes the verdict was in: "YJIT is no longer experimental", having "been tested on production workloads for over a year and proven to be quite stable". Note what that sentence implies. The production workload doing the testing was Shopify's, which is the deal a company makes when it improves its own constraint: it ships the risk first and the benefit to everyone.
The same decision is now being made a second time, and the record is honest about the price. Ruby 4.0 ships ZJIT, a method-based compiler that uses interpreter profiles, as experimental, with the note that "ZJIT is faster than the interpreter, but not yet as fast as YJIT" and a stated goal of becoming "production-ready in Ruby 4.1". Four years after the first compiler stabilised, the second one is slower than the one it is meant to replace. Buying your constraint is not a one-off purchase; it is a standing team.
| Decision | Chosen | Rejected | Because | Flips when | Evidence |
|---|---|---|---|---|---|
| Contain a slow dependency | In-process circuit breaker and bulkhead | Sidecar or mesh-level ejection | No extra hop; many worker processes per host make host-local semaphores meaningful | Few processes per host, or the resource is shared across languages | semian |
| Exercise failure | Fault injection in every dev and test environment since 2014 | Periodic game days in staging | Containment that is not exercised daily is theatre | Never; the cheaper variant is to run the same tool in fewer environments | toxiproxy |
| Ship to Kubernetes | A thin verdict layer over kubectl | An in-house orchestrator or PaaS | The gap was "Did it work?", not scheduling | Deploys must coordinate several clusters plus data migration; then the wrapper becomes a workflow engine | krane |
| Run extension code | WebAssembly modules, size-capped | A plugin API inside the host runtime | Untrusted code on the request path needs an admission rule that is mechanical | Your own language has no small Wasm target, at which point the sandbox excludes you too | ruvy |
| Own a tool long-term | Donate it once it is no longer differentiating | Keep it in the company organisation | bootsnap now lives under rails, javy under the Bytecode Alliance | The tool still encodes something you need to keep changing on your own schedule | bootsnap |
| Storefront framework | Adopt a third-party framework, then acquire its team | Continue the in-house framework | The in-house one was superseded; its repository was moved out and marked legacy | Acquisition does not buy the ecosystem underneath, so the churn continues regardless | hydrogen-v1 |
The storefront row deserves its own paragraph, because it is the one that contradicts the
rest. Hydrogen's first generation was Shopify's own React framework; it now sits in a
separate repository behind a legacy banner pointing at its successor, while still cutting
releases on a branch named v1.x-2022-07 as late as March 2025. The second
generation was built on Remix, whose team Shopify acquired. Remix's data APIs were then
moved down into React Router, a decision recorded in the open and dated 29 July 2022, and
React Router's later conventions shipped with an adapter package specifically to carry Remix
users across. The current Shopify Hydrogen README describes itself as "designed to dovetail
with React Router", and the Remix repository now opens with "Welcome to Remix 3!" and a set
of principles that includes "Model-First Development (optimizing for LLMs)". Owning the
framework did not stop the movement, because the movement was coming from the layer below
it.
Four failure threads recorded in issue trackers rather than in incident reports. Read the blast-radius rows carefully: none of these is a published outage.
An honest caveat before the cards. Shopify does publish incident analysis, but not on a host this session could reach. What follows is the next best public record: engineers inside and outside the company describing a failure mode precisely enough to be actionable, with numbers where they gave them. Three of the four threads are still open, which is itself the most transferable fact in this section. A known failure mode with an unmerged fix is the normal state of production software, and the design rule has to work in that state.
ignored_columns, which the maintainer describes as action at a distance. Canary deploys widen the window by design. Filed April 2023, still open.data_version UUID so a stale fill can be detected after the fact.Errno::EACCES during boot, so the process did not start at all. The report is specific about where it hurts: worker processes running from read-only images.Everything quantitative found in the corpus, with the artefact it came from and the date it was read. Where a figure has no date, the artefact did not carry one.
| Metric | Value | At | Context | As of | Source |
|---|---|---|---|---|---|
| Platform boot time | 25s to 6.5s | Shopify | Roughly 75% faster after path pre-scanning and compile caching | read 2026-09 | bootsnap README |
| Boot time, second operator | 6s to 3s | Discourse | Roughly 50%, reported by the operator in the same README | read 2026-09 | bootsnap README |
| Boundary check, whole monolith | 3m30s to under 20s | Shopify | Hot content-addressed cache; cold cache is unchanged | 2022-02 | packwerk PR #169 |
| Build cache size | ~200 MB | Shopify | Compared in the PR with bootsnap at 99 MB and Sorbet at 148 MB | 2022-02 | packwerk PR #169 |
| Capacity spent probing a dead resource | 16.7% | Shopify | Default MySQL settings, 1.0s half-open timeout against a 5.0s error timeout; 8.3% with bulkheads | 2019-07 | semian issue #244 |
| Wasm module, dynamic linking | 1 to 16 KB | Javy | The size class an extension platform can afford per request | read 2026-09 | javy README |
| Wasm module, static linking | at least 869 KB | Javy | Same toolchain, interpreter embedded; two orders of magnitude larger | read 2026-09 | javy README |
| JIT code memory ceiling | 64 MiB | Ruby 3.2 | Default --yjit-exec-mem-size; call threshold defaulted to 30 | Ruby 3.2 | Ruby 3.2 NEWS |
| Production exposure before "not experimental" | over a year | Ruby / Shopify | "tested on production workloads for over a year and proven to be quite stable" | Ruby 3.2 | Ruby 3.2 NEWS |
| Second JIT, relative speed | slower than YJIT | Ruby 4.0 | "faster than the interpreter, but not yet as fast as YJIT"; target is production readiness in 4.1 | Ruby 4.0 | Ruby 4.0 NEWS |
| Legacy storefront framework, last release | 2025-03-19 | Shopify | Branch v1.x-2022-07, years after the successor shipped | 2025-03 | hydrogen-v1 commits |
| Driver adoption to upstream | 11 days | Rails | Adapter PR opened 2023-04-06, merged 2023-04-17, after the monolith had run it for weeks | 2023-04 | rails PR #47880 |
Three of these are worth planning against directly. The 16.7% figure is the only public measurement in the corpus of what circuit-breaker recovery costs, and it generalises: the tax is the half-open timeout divided by the sum of the half-open and error timeouts, multiplied by the fraction of workers allowed to probe. Set those three numbers deliberately and you have chosen your recovery budget; leave them at defaults and you have inherited someone else's. The Javy size figures are the admission rule for extension platforms, and the ratio between them, roughly fifty to one, is why dynamic linking of a shared engine is not an optimisation but a precondition. The boundary-check figures set expectations for anyone adding static enforcement to a large codebase: assume minutes before caching, assume tens of seconds after, and assume a cache measured in hundreds of megabytes on every developer machine and CI node.
Every figure here is self-reported by the team that built the thing, in its own repository, and none has been independently reproduced. The boot-time and check-time numbers are the strongest, because they are reproducible by anyone with the code. The 16.7% is a calculation from stated defaults rather than a production measurement, and the issue presents it as such. No figure in this corpus describes request-level performance of the Shopify platform itself, because no such figure appears in a repository reachable from this session.
Thirty-two cards here, thirty-six rows in the ledger that ships beside this
page as sources.md, every one fetched on 11 September 2026 and every one from
the same two hosts. Filter by kind.
This session's network policy reached github.com and
raw.githubusercontent.com and nothing else. Shopify's engineering blog,
railsatscale.com, Ruby's issue tracker, conference video and the MPLR 2023 YJIT paper were
all tested and all blocked. There are therefore zero blog, talk and paper rows in this
ledger, and that absence is a property of the session rather than of the topic. Two
documents this guide can name but could not read are worth a reader's time on an
unrestricted network: "A Packwerk Retrospective" by Gannon McGibbon and Chris Salzberg,
named in the pull request below, and the MPLR 2023 YJIT evaluation cited in Ruby's own
documentation.
An engineer quantifies how much worker capacity is consumed probing a dependency that is still down, at the library's own default timeouts, and proposes tying ticket counts to circuit state. Open since July 2019.
The maintainer describes how schema-versioned cache keys create a one-directional invalidation window during any rollout, how ordinary a trigger can be, and proposes moving the schema hash into the value with a UUID data version.
A read-only container image turns a boot accelerator into a boot blocker, with the exact errno in the report. The requested behaviour, warn and continue, is the general rule for every performance cache.
The repository states that its Wasm modules exceed the maximum size Shopify Functions accepts, lists ideas rather than a plan, and was archived read-only on 27 January 2026.
Failure containment for a monolith, running since October 2014, with adapters for MySQL2, Redis, Net::HTTP and both Active Record adapters. No sidecar, no extra hop.
Built because existing tools "didn't provide the kind of dynamic API we needed for integration and unit testing", and used in all development and test environments since the same month Semian went in.
An outside contributor takes the whole-monolith check from three and a half minutes to under twenty seconds with a content-addressed cache, and documents the cache size next to bootsnap's and Sorbet's.
A contributor proposes linking Shopify's Packwerk retrospective from the README. A maintainer declines: "Those articles get old and change and might no reflect what the tooling is anymore."
Six months of work, closed unmerged, on classifying Trilogy's errors well enough for a circuit breaker: the driver "seems eager about closing unused connections" and the half-open timeout needed new client instances.
Interruptible, resumable background jobs, used "to interrupt workloads safely when moving tenants between shards and move shards between regions". The clearest public statement of how the platform is partitioned.
"IdentityCache is never going to be 100% consistent, since cache invalidations can be lost", followed by the list of ways they are lost, from skipped callbacks to Memcached restarts.
Packages, public constants, and an epigraph that frames the whole strategy: "This knowledge is a dependency that raises the cost of change." The tool is still receiving pull requests in 2026.
package_todo.yml records existing violations to be "worked off over time";
enforce_dependencies: strict stops new ones being recorded at all. Two
settings, two eras of a codebase.
"A lightweight, minimalistic Ruby JIT built inside CRuby" using basic block versioning, written in Rust, with production stories solicited to a Shopify address and an MPLR 2023 paper cited for the evaluation.
"A method-based just-in-time (JIT) compiler for Ruby" that "uses profile information from the interpreter to guide optimization", described as an advanced prototype.
Promotion justified by production exposure: "tested on production workloads for over a year and proven to be quite stable", with a 64 MiB default code budget and a call threshold of 30.
"As of Ruby 4.0.0, ZJIT is faster than the interpreter, but not yet as fast as YJIT", with production readiness targeted for 4.1 and Rust 1.85 required to build it.
"YJIT has been merged upstream, and is now an official part of Ruby 3.1+", with bug reports redirected to Shopify's fork of CRuby. The strategy in one banner.
Continuous benchmarking and statistics for the JIT, published at speed.ruby-lang.org. A public scoreboard is how an upstream investment stays accountable to the company paying for it.
Shopify "adopted Trilogy successfully in our Rails monolith several weeks ago" and then proposed the adapter to Rails, deliberately copying code verbatim first and cleaning up later. Merged eleven days after opening.
"Designed for performance, flexibility, and ease of embedding. It's currently in production use on github.com", with no dependencies beyond POSIX, libc and OpenSSL.
"The core Shopify platform boots about 75% faster, dropping from around 25s to 6.5s",
alongside Discourse's independent 50%. The gem now lives under rails/.
Modules of "1 to 16 KB range with use of dynamic linking" against "at least 869 KB" statically linked. The same toolchain, two orders of magnitude apart.
Built because kubectl "leaves its users with some burning questions: What just happened? Did it work?" Renamed from kubernetes-deploy at 1.0, and still tracking current Kubernetes releases.
"Used Shipit to synchronize and deploy hundreds of projects across dozens of teams, using Python, Rails, RubyGems, Java, and Go", and it works with anything deployable by a script.
"Hydrogen is designed to dovetail with React Router", and "Hydrogen legacy v1 has been moved to a separate repo". Two sentences that describe a whole storefront strategy.
Behind a legacy banner, yet still cutting releases on branch
v1.x-2022-07 as late as 19 March 2025, years after the successor.
The decision, accepted 29 July 2022, to move Remix's loaders, actions and fetchers down into React Router, with router logic extracted into a zero-dependency package and hooks renamed along the way.
Acknowledges that "when Remix changed its routing conventions between v1 and v2, some users experienced friction", and ships a dedicated adapter package to carry Remix route config into React Router v7.
"So you're asking Remix adopters to migrate Remix to React Router to Remix at some future date?", and from another commenter, "started three remix projects over the past 12 months and the setup was totally different every time".
"Welcome to Remix 3! The fully-stacked web framework", under active development, with stated principles including "Model-First Development (optimizing for LLMs)" and "Minimizing dependencies".
A fork of ruby/ruby carrying more than 100,000 commits, used as the intake for JIT bug reports. Owning the constraint starts with being able to build it.
Six rungs. The first three can be done against a toy application; the last three only mean something against a codebase somebody else also works in.
List the five substrates you could not replace in a quarter: language runtime, web framework, database driver, orchestrator, front-end framework. For each, answer three questions with evidence rather than opinion. Can we build it from source today? Has anyone here landed a change upstream? Do we know who decides its roadmap?
Done when: every row has a yes or no with a link, and at least one row surprises someone in the room. Teaches: leverage is measurable, and it is usually lower than assumed.
Wrap one dependency in a circuit breaker with a host-local concurrency limit. Then use a fault-injection proxy to hold it down and watch the recovery path specifically: how many workers probe, for how long, and what fraction of capacity that is.
Done when: you can state your recovery tax as a percentage, the way semian #244 does. Teaches: the breaker's defaults are a capacity decision somebody else made for you.
Take the slowest batch job you own and give it a checkpoint per record. Deploy over it, evict the pod mid-run, and prove it resumes without reprocessing. Then answer the harder question: could you move the tenant this job is working on to another shard right now?
Done when: a mid-run kill leaves no duplicates and no lost work, verified by counting rows. Teaches: data mobility is a property of your job framework before it is a property of your database.
Introduce static package boundaries into a real codebase. Record every existing violation into a todo file, fail the build only on new ones, and measure the check on a cold and a hot cache. Publish both timings to the team before turning it on in CI.
Done when: the check runs in CI, the todo file is shrinking month over month, and nobody has asked to disable it. Teaches: modularisation is a ratchet with a build-time price tag, not a migration.
Compile a small function to WebAssembly and call it on a request path. Measure module size and cold start. Then compile the same logic from the language your platform is written in, and compare. Write down the size limit you would enforce and who it excludes.
Done when: you have two module sizes, two cold-start numbers, and a written admission rule. Teaches: the sandbox is a separate platform with its own economics, which is exactly what Ruvy ran into.
Fork the runtime you scored highest on in rung one. Apply a small change you actually want, build it, run your test suite against it, and rebase weekly for four weeks. Track the hours. That number is the true cost of the "we could always fork it" answer that every architecture review accepts without evidence.
Done when: you can state the monthly cost of carrying one patch, and decide on that basis whether upstreaming is cheaper. Teaches: forking is a subscription, and upstreaming is how you cancel it.
The queries that produced this page, against a network that reached only one host. They work on any company with a public repository presence.
site:github.com <org> archived "no longer maintained"site:github.com <org> "has been moved to a separate repo" legacysite:github.com <org> "is not currently compatible with"github.com/<org>/<repo>/pulls?q=is:pr+is:closed+is:unmergedsite:github.com <org> decisions "0001" OR "Status: Accepted"site:github.com <repo> discussions "please reconsider"site:github.com <org> issue "in production since"site:github.com <org> pull request "reduced from" seconds minutessite:github.com <org> "% of capacity" OR "of our capacity" issueraw.githubusercontent.com <org>/<repo>/main/README.md "never going to be"site:github.com <org> issue "can be missed" OR "can be lost" invalidationsite:github.com <repo> issue "in production" errno OR "failed to boot"One technique did most of the work here and is worth stating on its own. When a blog host is unreachable, the same facts are often inside a repository, written for a different purpose: a README that dates a system to a month, a pull-request description that carries a before-and-after timing, an issue that quantifies a failure mode because the author needed to justify the fix. Those sentences were written to persuade a colleague, which makes them better evidence than the post that was written to be found.