[opensourcedex]

FluidFramework is a free, open source collaboration & communication project written in TypeScript and released under MIT. It has 4,946 GitHub stars, 586 forks and 207 open issues, and was last pushed 5 hours ago. On this registry it ranks #21 of 41 tracked projects in Collaboration & Communication, with 5 head-to-head comparisons available.

What is FluidFramework?

FluidFramework is an MIT-licensed TypeScript library from Microsoft for building distributed, real-time collaborative web applications in JavaScript or TypeScript, aimed at developers who need shared, synchronized state across many clients without assembling that synchronization layer themselves.

What it is

FluidFramework is a library and accompanying service stack for distributed, real-time collaborative web applications. The repository holds the core code for both the Fluid client packages and the reference ordering service, so the client-side data structures and the server-side ordering machinery live in one place. Packages are published to npm across several namespaces: @fluidframework/ for the main libraries, @fluid-experimental/ for experimental work, @fluid-tools and @fluid-internal/ for tooling and private packages, and @fluid-example/ for unpublished examples.

The concrete problem it solves is the one every collaborative app hits: keeping multiple clients' state consistent as edits arrive concurrently. Instead of each team building and operating its own ordering backend, transport, and merge logic, FluidFramework supplies client libraries plus a reference ordering service named routerlicious, supported by the microservices gitrest and historian. In practice that replaces a hand-rolled synchronization and relay service with a published set of npm packages and a reference server implementation in the same repository.

Key capabilities

  • Client-side and server-side packages under the @fluidframework/ namespace, with experimental APIs under @fluid-experimental/ and non-published examples under @fluid-example/.
  • A reference ordering service, routerlicious, located in ./server/routerlicious, with supporting microservice packages in ./server, gitrest, and historian.
  • CRDT-based data structures for distributed, real-time collaboration, as reflected in the repository topics.
  • Monorepo organized as pnpm workspaces called "release groups" — client, routerlicious, gitrest, historian, and build-tools — where packages inside one workspace are versioned together but the workspaces are versioned separately from one another.
  • Documented version-range guidance: a ^ caret range such as ^1.3.4 for public APIs, and a more restrictive ~ tilde range for unstable or beta APIs.
  • A build step called layer-check that enforces dependency rules between packages in the various layers of the system.
  • Documentation at fluidframework.com, plus the Hello World repo and Core Examples repo, with questions handled in the repository's GitHub Discussions section.

Who uses it and how

  • Application teams building collaborative web experiences in JavaScript or TypeScript that need shared state to converge across concurrent editors.
  • Self-hosting operators running the reference ordering service, routerlicious, together with the gitrest and historian microservices as the server side of a Fluid deployment.
  • Front-end developers consuming the published npm packages, pinning public APIs with caret ranges and beta APIs with tilde ranges to absorb upstream changes safely.
  • Contributors working inside the release-group structure, where the client workspace is rooted at the repository root and the service workspaces are rooted under ./server/.
  • New adopters following the Hello World and Core Examples repositories before integrating the libraries into an existing product.

Getting started

The README directs new users to the documentation and guides at fluidframework.com, with the Hello World repo and Core Examples repo as starting points. Library consumption is a standard npm dependency on the @fluidframework/ packages, using a caret version range such as ^1.3.4 for public APIs and a ~ range for unstable or beta APIs.

How it compares

No list of paid or commercial products that this project replaces is provided in the available facts, and the facts do not name any directly comparable tools. On the evidence given, FluidFramework stands alone in this registry under Business Software / Collaboration & Communication.

When to use it — and when not to

Adopting FluidFramework means operating real infrastructure: the reference ordering service, routerlicious, plus the gitrest and historian microservices, and the client libraries themselves. Teams that want a turnkey hosted collaboration product, or that cannot maintain a multi-workspace pnpm monorepo and its separately versioned release groups, should look elsewhere. The repository also carries 207 open issues and an excerpted README that defers heavily to external documentation, so expect to lean on the docs and the discussion forum rather than the README alone.

project readme (upstream, from github) — read inline

Fluid

The Fluid Framework is a library for building distributed, real-time collaborative web applications using JavaScript or TypeScript.

Getting started using the Fluid Framework

You may be here because you want to...

  • Learn more about the Fluid Framework
  • Build a Fluid object

Documentation and guides can be found at .

Hello World repo can be found at .

Core Examples repo can be found at .

Have questions? Engage with other Fluid Framework users and developers in the Discussions section of our GitHub repo.

Using Fluid Framework libraries

For a dependency on a Fluid Framework library's public APIs, we recommend a ^ (caret) version range. For example, use ^1.3.4.

For a dependency on an unstable API, such as a beta API, we recommend a more restrictive version range. For example, use a ~ version range.

Code structure

The core code for both the Fluid client packages and the reference ordering service is contained within this repo.

The repo structure is somewhat unique because it contains several pnpm workspaces: some for individual packages and some for larger collections which we call "release groups". The workspaces are versioned separately from one another, but internally all packages in a workspaces are versioned together.

These workspaces do not align with package namespaces, and also don't always correspond to a single directory of this repo.

Here's the list of release group workspaces:

Here's a list of other sets of other packages (each package within these groups is versioned independently, forming its own release group):

  • "Common" Packages: miscellaneous packages in the ./common directory and published under the @fluidframework/ namespace. Most of these (but not all) have "common" in their package name. Packages which are used by multiple other groups of packages (such as built tools, linter configs and protocol definitions) live here.
  • "Tools" Packages: miscellaneous packages in the ./tools directory and published under a variety of namespaces. Logically about the same as "Common", but most of the names include "tools" instead of "common".
  • Auxiliary Microservice Packages (supporting Routerlicious)
    • ./server excluding routerlicious, gitrest and historian (Published in the @fluidframework/ namespace)
  • ./docs: The code and content for .

Dependencies between packages in various layers of the system are enforced via a build step called layer-check. You can view the full list of packages and layers in PACKAGES.md.

  • Note: to update the contents of PACKAGES.md for local package changes, run pnpm layer-check --md ..

Setup and Building

Install the required tools:

Clone a copy of the repo and change to the repo root directory:

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

Enable NodeJs's corepack:

corepack enable

[!NOTE] Microsoft developers: due to internal policy, the public npm registry (registry.npmjs.org) is blocked on managed devices. Refer to our internal team onboarding guidance for details on how to contribute, either by getting an exception or by using the helper script at scripts/set-dev-registry.cjs appropriately.

Run the following to build the client packages:

pnpm install
npm run build

You can use the worker mode to get faster build time as well: npm run build:fast

See also: Contributing

Build in VSCode

To build Fluid Framework within VSCode, open the Fluid Framework repo folder as a work space and use Ctrl-Shift-B to activate the build task. It is the same as running npm run build on the command line.

NodeJs Installation

We recommend using nvm (for Windows or MacOS/Linux) or fnm to install Node.js. This ensures you stay at the correct version while allowing other uses of NodeJS to use the (possibly different) versions they need side-by-side.

Because of a transitive dependency on a native addon module, you'll also need to ensure that you have the prerequisites for node-gyp. Depending on your operating system, you'll have slightly different installation requirements (these are largely copied from node-gyp's documentation):

On Windows

The node installer should ask if you want to install "Tools for Native Modules." If you check the box for this nothing further should be needed. Otherwise, you can follow the steps listed here

On Unix

  1. Python v3.7, v3.8, v3.9, or v3.10
  2. make
  3. A C/C++ toolchain (like GCC)

On MacOS

If you've upgraded your Mac to Catalina or higher, you may need to follow these instructions.

  1. Python v3.7, v3.8, v3.9, or v3.10
  2. XCode Command Line Tools, which will install make, clang, and clang++
    • You can install these by running xcode-select --install from a command line.

Other Build Requirements

  • Building server/Routerlicious
    • Refer to that package's README for additional requirements.
    • Note that these requirements do not affect all workflows (e.g. the one noted above), but will affect workflows that include the packages under server.
On Windows
  • Ensure that you have enabled running Powershell scripts by setting your environment's Execution Policy.

Other Build Commands

Building our docs

There are a few different areas in which we generate documentation content as a part our overall build.

  1. fluidframework.com
    • We build the contents of our public website from the docs directory under the root of this repo. See its README for more details.
  2. Generated README contents
    • We leverage a local tool (markdown-magic) to generate / embed contents in our various package-level READMEs. This is done as a part of a full build, bu

readme truncated — read the full docs on github

Frequently asked questions

Is FluidFramework free to use?

FluidFramework is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does FluidFramework do?

Library for building distributed, real-time collaborative web applications

What is FluidFramework written in?

FluidFramework is primarily written in TypeScript. Its source is publicly available at https://github.com/microsoft/FluidFramework, and it has 4,946 GitHub stars.