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 https://fluidframework.com/.

Hello World repo can be found at https://github.com/microsoft/FluidHelloWorld.

Core Examples repo can be found at https://github.com/microsoft/FluidExamples.

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:

• client (previously known as "Fluid Framework Client" or "core") (Rooted in ./. Configured by ./pnpm-workspace.yaml)
  • ./packages (Published in the @fluidframework/ namespace, but some in @fluid-tools and unpublished packages in @fluid-internal/)
  • ./experimental (Published in the @fluid-experimental/ namespace)
  • ./examples (Not published, live in the @fluid-example/ namespace)
  • ./azure. (Published in the @fluidframework/ namespace)
• routerlicious (Reference Fluid Ordering Service) (Rooted in ./server/routerlicious. Configured by ./server/routerlicious/pnpm-workspace.yaml)
  • Packages (Published in the @fluidframework/ namespace)
• gitrest (Rooted in ./server/gitrest. Configured by ./server/gitrest/pnpm-workspace.yaml)
  • Packages (Published in the @fluidframework/ namespace)
• historian (Rooted in ./server/historian. Configured by ./server/historian/pnpm-workspace.yaml)
  • (Published in the namespace)

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 https://fluidframework.com.

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:

• Git.
  • + Git LFS
• Node.js: install the version noted in in the .nvmrc file. See NodeJs Installation for details.

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

[!WARNING] Corepack cannot currently download an uncached pnpm version from publicPackages because Azure Artifacts does not support its single-version metadata endpoint. corepack enable can succeed while the next pnpm command fails. If direct npmjs access is blocked, use the npm-based pnpm bootstrap workaround.

[!NOTE] Dependencies come from the public Azure Artifacts publicPackages feed. Existing saved packages can be downloaded without credentials. Maintainers need to authenticate to save new packages from npmjs. See Dependency setup and changes for authentication, troubleshooting, and the maintainer-assisted workflow for external contributors.

This is the beginning of the README. Read the rest at the original. Read the full README ↗