Fluid

Library for building distributed, real-time collaborative web applications

Real-time
microsoft/FluidFrameworkfluidframework.com

README

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.

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 five monorepos as well as several standalone packages. The
monorepos are managed using Lerna and are versioned separately from one another, but internally
all packages in a monorepo are versioned together. Outside the monorepos there are plenty of packages which are
versioned independently.

These monorepos (which also serve as "release groups") do not necessary align with package namespaces,
and also don't necessary correspond to a single directory of this repo.

Here's the list of Lerna managed release groups:

-   core (previously known as "Fluid Framework Client" or "Client") (Rooted in ./. Configured by ./lerna.json)
    -   ./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 (Rooted in ./azure. Configured by azure/lerna.json)
    -   Packages (Published in the@fluidframework/ namespace)
-   routerlicious (Reference Fluid Ordering Service) (Rooted in ./server/routerlicious. Configured by ./server/routerlicious/lerna.json)
    -   Packages (Published in the@fluidframework/ namespace)
-   gitrest (Rooted in ./server/gitrest. Configured by ./server/gitrest/lerna.json)
    -   Packages (Published in the@fluidframework/ namespace)
-   historian (Rooted in ./server/historian. Configured by ./server/historian/lerna.json)
    -   Packages (Published in the@fluidframework/ 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](./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.

Building


In order to build the Fluid Framework, ensure that you have installed Git and the version of
Node.js noted in the .nvmrc file.

Note: we recommend using nvm (for Windows or
MacOS/Linux) or fnm to install Node.js, in case you find yourself needing to install different
versions of Node.js 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.

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

  1. ``` sh
  2. git clone https://github.com/microsoft/FluidFramework.git
  3. cd FluidFramework
  4. ```

Run the following to build the client packages:

  1. ``` sh
  2. npm install
  3. npm run build:fast
  4. ```

See also: Contributing

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 underserver (e.g. fluid-build --symlink:full).

On Windows


-   Ensure that you have enabled running Powershell scripts by setting your environment's Execution Policy.

Testing


You can run all of our tests from the root of the repo, or you can run a scoped set of tests by running the test
command from the package you're interested in.

Note: Some of the tests depend on test collateral that lives in a submodule here:
. You may choose to fetch that collateral into your local
repository, which is required to run all the tests - otherwise some will be skipped.

First install Git LFS from . Then, from the repo root:

  1. ``` sh
  2. git lfs install
  3. git submodule init
  4. git submodule update
  5. ```

Run the tests


  1. ``` sh
  2. npm run test
  3. ```

Include code coverage


  1. ``` sh
  2. npm run test:coverage
  3. ```

Mimic the official CI build


Our CI pipelines run on Linux machines, and the npm scripts all have the ci prefix.
To replicate the test steps from the CI pipeline locally, run the following commands for the packages or Lerna monorepos:

RunNon-WindowsWindows
-------------------------------------------------------------------------------------
PR`npm`npm
Official`npm`npm

Run tests from within VS Code


We've checked in VS Code configuration
enabling F5 from a spec.ts file to run those tests if you set the debug configuration to "Debug Current Test".

Run it locally


Single browser window, two panes


_This will use an in-memory implementation of the Fluid server to sync between the two panes in the browser window._

-   Choose an example under /examples
-   Navigate to the example's directory, e.g. /examples/data-objects/clicker
-   npm run start
- Browse to to interact with two copies of the example side-by-side

Multiple browser instances on the same device


_This will run the local Fluid server implementation we call "Tinylicious", so you can sync between multiple browser
instances._

First, start Tinylicious by running these commands from /server/tinylicious:

  1. ``` sh
  2. npm install
  3. npm run build
  4. npm run start
  5. ```

Then:

-   Navigate to the example of your choice (same as above)
-   npm run start:tinylicious
- Browse to copy the full URL you're redirected to, and open in a second window to collaborate

Contributing


There are many ways to contribute to Fluid.

-   Participate in Q&A in our GitHub Discussions.
-   Submit bugs and help us verify fixes as they are checked in.
-   Review the source code changes.
-   Contribute bug fixes.

Detailed instructions for working in the repo can be found in the
Wiki.

This project has adopted the Microsoft Open Source Code of Conduct.
For more information see the Code of Conduct FAQ or contact
opencode@microsoft.com with any additional questions or comments.

This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services. Use of these
trademarks or logos must follow Microsoft’s Trademark & Brand Guidelines. Use of
Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft
sponsorship.