Microsoft Fluid Framework: a CRDT library for real-time collaborative web apps

The problem Fluid Framework addresses, and who it is for

Two people editing the same document in a browser is easy to demo and hard to ship. The hard part is not the socket; it is agreeing on what the document contains after both clients have written to it while disconnected from each other. Fluid Framework is aimed at that problem. The README describes it as a library for building distributed, real-time collaborative web applications using JavaScript or TypeScript, and the repository topics include collaboration, crdt, datastructure, distributed and realtime.

The audience is application developers who want shared state as a data structure rather than as a stream of messages. If you are writing a whiteboard, a co-editing surface, a shared task list or anything where multiple clients mutate the same object graph, the library gives you distributed data structures and a sync layer rather than asking you to invent a merge policy. The README points newcomers at two companion repositories: FluidHelloWorld for a minimal example and FluidExamples for core examples. That split is telling. The main repository is the framework and the reference server, not a tutorial.

How the client and the reference ordering service fit together

The README states that the core code for both the Fluid client packages and the reference ordering service lives in this repository. That single sentence explains most of the layout. On the client side you get the distributed data structures and the runtime that connects them to a service. On the server side you get routerlicious, described in the README as the Reference Fluid Ordering Service, rooted at server/routerlicious and configured by its own pnpm-workspace.yaml.

The repository is split into pnpm workspaces, some for individual packages and some for larger collections the README calls release groups. The release groups are client, routerlicious, gitrest, historian and build-tools. Packages inside a release group are versioned together even though the groups are versioned separately from one another. The README is explicit that workspaces do not line up with package namespaces and do not always correspond to a single directory, which is why the client group is rooted at the repository root and configured by the top-level pnpm-workspace.yaml rather than by a subdirectory.

Dependencies between layers are enforced by a build step called layer-check, and the full package and layer listing lives in PACKAGES.md. If you plan to depend on Fluid packages, that file is the map. Running pnpm layer-check --md . regenerates it for local changes, according to the README.

Installing the repository and running a first build

The README's setup path is for working in the repository itself, not for adding the library to an application. It asks for Git with Git LFS, and Node.js at the version noted in the .nvmrc file. Clone and enter the repository:

git clone https://github.com/microsoft/FluidFramework.git
cd FluidFramework

Enable Node.js corepack, which is what provides the pnpm version the workspace expects:

corepack enable

Then install and build the client packages. The README gives these two commands:

pnpm install
npm run build

The README notes that npm run build:fast uses worker mode for a faster build. The package.json shows that both build and build:fast map to fluid-build --task build, so the difference is in how the build tool schedules work rather than in what is built. Expect a long first install: the repository holds client packages, several server workspaces and build tooling in one checkout.

If you work in Visual Studio Code instead, the README says to open the repository folder as a workspace and press Ctrl-Shift-B, which runs the same task as npm run build. One caveat the README raises for Microsoft developers: the public npm registry is blocked on managed devices, and the internal guidance points at scripts/dev-registry.cjs for an alternative registry configuration.

Version ranges, release groups and the upgrade surface

The README's dependency guidance is short and worth following literally. For a dependency on a Fluid Framework library's public APIs it recommends a caret version range, with ^1.3.4 as the example. For an unstable API such as a beta API it recommends a more restrictive range, with ~1.3.4 as the example. That is a deliberate acknowledgement that the beta surface moves faster than the stable one.

The upgrade cost comes from the release group model. Packages inside a group move together, so pulling one client package forward can drag its siblings with it. The repository carries several documents that exist precisely because cross-version behaviour is not free: BREAKING.md, CompatibilityCheckpoints.md, CrossClientCompatibility.md, CrossClientCompatibilityDevGuide.md, FluidCompatibilityConsiderations.md, LayerCompatibility.md, LayerCompatibilityDevGuide.md and LayerCompatibilityUnified.md. The presence of that many compatibility documents is the clearest signal in the repository that version alignment is an ongoing operational concern rather than a one-time setup step.

Recent releases follow a minor and patch cadence: client_v3.1.0 as a minor on 2026-09-16, with client_v3.0.2 and client_v3.0.1 as patches before it. The root package.json declares version 3.2.0 for the client release group root. The repository is not archived, and the last push was on 2026-09-22.

Where Fluid Framework is the wrong choice

The README frames the project as a library, and that framing is the main limitation. There is no hosted service described in the documentation. You get client packages and a reference ordering service in the same repository, which means the operational half of a collaborative application is yours to run or to source elsewhere. If you want to add collaboration to an existing app by pointing it at a managed endpoint and forgetting about it, this is not that.

The second boundary is language. The README says the library is for JavaScript or TypeScript. A Python or Go backend that needs to participate in the same shared data structure is outside what the documentation describes.

The third is the build itself. The README requires Git LFS, a specific Node.js version from .nvmrc, corepack, pnpm, and node-gyp prerequisites because of a transitive dependency on a native addon module. The README notes that those prerequisites differ by operating system and points at node-gyp's documentation rather than reproducing it. On a machine where native module compilation is restricted, the build is the first obstacle, before any application code exists. And if your collaboration problem is plain text editing, a text-oriented CRDT library is a shorter path than adopting a general distributed data structure framework and building the editor binding yourself.

Azure Fluid Relay and other alternatives

Azure Fluid Relay appears in the search terms people use around this project, and the repository layout supports the connection: the client release group includes an azure directory published in the @fluidframework namespace, and the README lists azure packages as part of that group. The distinction to hold onto is that Fluid Framework is the library and the reference ordering service, while a hosted relay is the managed side of the same protocol. Choosing the hosted route changes who operates the service, not what the client code looks like.

The other real alternative is a text-oriented CRDT library. The difference is scope. A text CRDT gives you a sequence type tuned for character-level merging and an editor binding, and little else. Fluid Framework gives you distributed data structures as a general concept plus a runtime and a service contract, which is more machinery when you only need text and less machinery when your shared state is a map, a tree or a set of counters. If your document is a rich structured model that several clients mutate in different ways, the general approach earns its cost. If it is a paragraph, it does not.

The README also points to the Discussions section of the GitHub repository as the place to engage with other users and developers, which is the practical channel when the compatibility documents do not answer a version question.

Licence and what MIT means for the server code

The repository is MIT licensed, and the root package.json carries "license": "MIT" with author "Microsoft and contributors". MIT is permissive: it allows use, modification and redistribution, including in closed-source products, provided the copyright notice and permission notice are preserved. The LICENSE file at the repository root is the authoritative text, and NOTICE.md sits alongside it.

The detail worth noticing is that the MIT licence covers the reference ordering service as well as the client packages, since the README states both live in this repository. That means shipping a modified routerlicious or gitrest is not a licensing problem in the way a copyleft server component would be. It does not mean the service is production-ready for your workload; the README calls routerlicious the reference ordering service, and reference implementations carry different expectations than supported products. This is a description of the licence, not legal advice.

Editorial conclusion

Adopt Fluid Framework if you are building a JavaScript or TypeScript application where several people edit the same structured data at once and you are prepared to run or buy an ordering service. Do not adopt it if you want a hosted backend out of the box or if your collaboration model is plain text editing, where a text-focused CRDT is a shorter path. Before committing, verify the Node.js version in the .nvmrc file, check that your package manager is pnpm, and read PACKAGES.md and LayerCompatibility.md to confirm the packages you intend to depend on sit in layers you can consume.

Frequently asked questions

Official sources

1. License: MIT
2. microsoft/FluidFramework on GitHub
3. Project website
4. README
5. Releases