microsoft / FluidFramework

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 When taking a dependency on a Fluid Framework library's public APIs, we recommend using a (caret) version range, such as . While Fluid Framework libraries may use different ranges with interdependencies between other Fluid Framework libraries, library consumers should always prefer . If using any of Fluid Framework's unstable APIs (for example, its APIs), we recommend using a more constrained version range, such as . 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 namespace, but some in and unpublished packages in ) • ./experimental (Published in the namespace) • ./examples (Not published, live in the namespace) • ./azure. (Published in the namespace) • routerlicious (Reference Fluid Ordering Service) (Rooted in ./server/routerlicious. Configured by ./server/routerlicious/pnpm-workspace.yaml) • Packages (Published in the namespace) • gitrest (Rooted in ./server/gitrest. Configured by ./server/gitrest/pnpm-workspace.yaml) • Packages (Published in the namespace) • historian (Rooted in ./server/historian. Configured by ./server/historian/pnpm-workspace.yaml) • Packages (Published in the namespace) • build-tools (Rooted in ./build-tools. Configured by ./build-tools/pnpm-workspace.yaml) • Packages (Published in a mix of and namespaces) 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 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 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 for local package changes, run . 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: Enable NodeJs's corepack: Run the following to build the client packages: You can use the experimental worker mode to get faster build time as well: 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 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 . Depending on your operating system, you'll have slightly different installation requirements (these are largely copied from '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 • Python v3.7, v3.8, v3.9, or v3.10 • • 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. • Python v3.7, v3.8, v3.9, or v3.10 • , which will install , , and • You can install these by running 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 . 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. • [fluidframework.com]() • We build the contents of our public website from the directory under the root of this repo. See its README for more details. • Generated README contents • We leverage a local tool (markdown-…