Garfish: a micro front-end framework for independently deployed sub-applications

What Garfish solves, and for whom

Garfish targets a specific organisational problem rather than a rendering one. The README states its goals as composing independently delivered front-end applications into a whole, and decomposing a front-end application into smaller ones that can be "independently developed", "independently tested" and "independently deployed", while still appearing to users as cohesive products. The stated motivations are cross-team collaboration, a diversified technology system, and growing application complexity.

That framing tells you who it is for. If one team owns one repository and one release train, Garfish adds a loader, a sandbox and a routing layer you do not need. It pays off when team A ships a Vue application, team B ships React, and both must appear inside a shell that a third team owns. The sub-application is expected to support "any kind of framework and technology system access", which is the point: the host does not dictate the sub-app's stack.

The README also notes that Garfish has been polished by a large number of online applications. That is a claim about production exposure, not a benchmark, and the repository gives no numbers behind it. Treat it as a signal that the API has survived contact with real traffic, not as a performance guarantee.

Loader, router, sandbox and store: the four moving parts

The README describes the core modules directly, and the split is the architecture. The Loader handles HTML entry and JS entry, which is how a sub-application is fetched and mounted. The Router is route-driven: the host configures a routing table, and Garfish handles independent rendering and destruction of the sub-app, plus master-child route isolation. The Sandbox provides runtime isolation for JS and CSS side effects. The Store is described as a simple mechanism for exchanging communication data between applications.

So the data flow is: a route change in the host matches the routing table, the Loader pulls the sub-app's entry (HTML or JS), the Sandbox wraps its execution so its globals and styles do not bleed into the host or into sibling sub-apps, the sub-app mounts, and Store carries whatever data the host and sub-app agreed to share. On route exit, the Router destroys the sub-app.

Two design choices are worth naming. First, HTML entry means the sub-app keeps its own build output, including its own asset URLs, which is what makes independent deployment real. Second, the sandbox is the load-bearing piece: everything else is plumbing, but isolation is where micro front-ends usually break. Garfish's README credits Qiankun for sandbox ideas and single-spa for routing and the bridge implementation, and says it forked the bridge code and adjusted it for Garfish lifecycles. That is candid attribution, and it also tells you the sandbox is a known-hard problem the project inherited rather than invented.

Installing Garfish and mounting a first sub-application

The README gives two install commands. Both are copied exactly as they appear there; pick one.

# npm
npm install garfish

# yarn
yarn add garfish

After installing, the README points to the documentation site for the actual wiring: the Quick Start page at garfishjs.org/guide/quick-start/start.html and the API reference at garfishjs.org/api. The README itself does not include a host bootstrap snippet, so there is no code here to copy for the router table or the sandbox configuration. That is a real friction point, and it is worth knowing before you start: the install is one line, but the first working host requires reading the guide.

The repository layout confirms the package split. The workspace has a packages/ directory, and the root build script runs pnpm --parallel --filter @garfish/* --filter garfish run build, so the published garfish package is one of several scoped @garfish/* packages. If you plan to extend behaviour, the README says the plugin mechanism is the extension point, and it names two plugins shipped with the project: css-scope, which is credited to reworkcss, and es-module, which is credited to @babel/traverse and es-module-shims. The README does not list the full plugin inventory, so check the packages directory rather than assuming a plugin exists.

Where Garfish is the wrong tool

The clearest limitation is documentation language. The README says the doc site is "only available in Chinese for now", with English versions planned. Everything the README links for setup, concepts and API lives on that Chinese site. An English-speaking team can still adopt Garfish, but it will be reading translated pages or source code for anything past installation. That is a cost, not a blocker, and it should be priced in before a decision.

The second limitation is the sandbox itself. Runtime isolation of JS and CSS is inherently a rewriting exercise: the framework intercepts what the sub-app does to shared globals and styles. The README does not document the escape hatches, the known unsupported patterns, or what happens when a sub-app depends on a global that the sandbox has already claimed. If your sub-app does anything unusual with document, window, or dynamically injected styles, verify it under Garfish before you commit, because the README gives no compatibility matrix.

Third, Garfish is the wrong tool if your applications are already one deployable unit. The framework's value comes from independent deployment; if you deploy everything together anyway, you have added a loader, a router and a sandbox to solve a problem you do not have.

Garfish and single-spa: different levels of the same problem

The README credits single-spa for the community wave of micro front-end solutions and says Garfish's routing system learned from it, and that Garfish forked single-spa's bridge implementation and adjusted it for Garfish lifecycles. That makes single-spa the natural comparison, but the two sit at different levels.

single-spa is a lifecycle and routing orchestrator. It registers applications, decides when each is active, and calls mount and unmount. It does not fetch your sub-app's HTML, and it does not isolate its globals; you assemble those pieces yourself or from other libraries. Garfish bundles the missing pieces: the Loader fetches HTML or JS entries, the Sandbox isolates runtime and style side effects, and the Store handles cross-app data. The README's own framing, that the Router means the user "does not need to care about the internal logic", is exactly the difference.

So the trade is control against integration. single-spa gives you a smaller primitive and expects you to choose your own loader and isolation strategy, which is useful when your constraints are unusual. Garfish makes those choices for you, which is faster when they are not. Garfish's own debt to single-spa is visible in the code lineage, so this is not a case of one replacing the other so much as one packaging the other's ideas with the entry and isolation layers attached.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-19, which is days before this writing. The most recent release listed is v1.19.12 on 2026-08-04, following v1.19.7 on 2026-01-04 and v1.19.4 on 2025-02-17. So releases arrive irregularly: roughly one per several months, with the 1.19.x line staying in place across that span. Within the 1.19 series the version numbers move, which suggests patch-level changes rather than a major API break, but the README does not document a deprecation or migration policy, and the CHANGELOG.md at the repository root is the place to check before upgrading.

The upgrade cost is dominated by the sandbox. Because isolation works by intercepting sub-app behaviour, a Garfish upgrade can change how a sub-app's globals or styles are handled even when your own code is untouched. Budget for re-running your sub-apps against a new version rather than assuming a patch bump is inert. The repository's test setup is visible in the root package.json: jest for unit tests, Cypress and a scripts/e2e.js runner for end-to-end, which is a reasonable signal that regressions are meant to be caught in CI.

On licence: the repository metadata reports NOASSERTION, which means the licence was not identified as a standard SPDX identifier. The repository contains a LICENSE file. Read that file directly and have whoever handles licensing at your organisation review it; nothing in the README describes the terms, and this article is not legal advice.

Editorial conclusion

Adopt Garfish if you have several front-end teams on different stacks that must ship independently but render as one product, and you can read the Chinese documentation or work from the API reference. Do not adopt it if you need English-first docs, a permissively clarified licence statement, or a framework that will not rewrite sub-app globals at runtime. Before committing, install garfish, build the smallest possible host plus one sub-app, and confirm that your sub-app survives the sandbox: check whether Garfish's own README lists the frameworks it claims to support, and read the LICENSE file rather than the repository metadata.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. web-infra-dev/garfish on GitHub