Registry / web-framework / fluid-framework

fluid-framework

JSON →
library2.93.0jsnpmunverified

The `fluid-framework` package serves as the primary client-side entry point for building collaborative applications with Fluid Framework. It bundles core Fluid Framework client libraries, including the `IFluidContainer` interface and various Distributed Data Structures (DDSes) like `SharedTree` and the now legacy `SharedMap`. The current stable version is 2.93.0, with minor releases occurring frequently, often including new features and breaking changes. This package abstracts away many individual Fluid package dependencies, simplifying development. While it provides the core collaborative primitives, it requires a separate service client (e.g., `@fluidframework/azure-client` or `@fluidframework/tinylicious-client`) to connect to a Fluid service. Its key differentiators include real-time, low-latency collaboration primitives, robust data modeling with `SharedTree`, and a comprehensive API for managing collaborative sessions.

npm install fluid-framework
INSTALL
IMPORT
SIG · FLUID-FRAMEWORK
F
fluid-framework
web-frameworkjavascriptv2.93.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

IFluidContainer
✓ import { IFluidContainer } from 'fluid-framework';
✗ const IFluidContainer = require('fluid-framework');
The `IFluidContainer` interface is a core public API. While `fluid-framework` primarily targets ESM, other associated packages like `@fluidframework/react` are ESM-only since v2.90.
SharedTree
✓ import { SharedTree } from 'fluid-framework';
✗ import { SharedTree } from 'fluid-framework/beta';
`SharedTree` is the recommended modern Distributed Data Structure (DDS) and is part of the public API, imported directly from `fluid-framework`.
TinyliciousClient
✓ import { TinyliciousClient } from '@fluidframework/tinylicious-client';
✗ import { TinyliciousClient } from 'fluid-framework';
Service clients like `TinyliciousClient` are provided by separate packages and are not re-exported directly from `fluid-framework`.
TreeAlpha
✓ import { TreeAlpha } from 'fluid-framework/alpha';
✗ import { TreeAlpha } from 'fluid-framework';
Alpha-level APIs, such as `TreeAlpha`, must be imported from their specific subpath (`fluid-framework/alpha`).

This quickstart demonstrates how to create or load a Fluid container, initialize a SharedTree with a defined schema, and interact with its collaborative data, including event listeners for changes.

import { SharedTree } from "fluid-framework"; import { TinyliciousClient } from "@fluidframework/tinylicious-client"; import { TreeConfiguration, SchemaFactory } from "@fluidframework/tree"; const client = new TinyliciousClient(); // Define the schema for our collaborative tree const sf = new SchemaFactory("my-app"); class MyTreeNode extends sf.object("MyTreeNode", { message: sf.string, timestamp: sf.number, children: sf.array(sf.reference("MyTreeNode")) }) {} const appSchema = new TreeConfiguration( [MyTreeNode], () => new MyTreeNode({ message: "Hello from Fluid!", timestamp: Date.now(), children: [] }) ); const containerSchema = { initialObjects: { myTree: SharedTree } }; async function startFluidClient() { const containerId = location.hash.substring(1); let container; if (!containerId) { // Create a new container ({ container } = await client.createContainer(containerSchema)); const tree = container.initialObjects.myTree.schematize(appSchema); tree.root.message = "Initial message"; tree.root.timestamp = Date.now(); const newChild = new MyTreeNode({ message: "First child", timestamp: Date.now(), children: [] }); tree.root.children.insertAtStart(newChild); const id = await container.attach(); location.hash = id; console.log("New container created with ID:", id); } else { // Get existing container ({ container } = await client.getContainer(containerId, containerSchema)); console.log("Existing container loaded with ID:", containerId); } const tree = container.initialObjects.myTree.schematize(appSchema); // Event listener for changes tree.events.on("treeChanged", () => { console.log("Tree changed: Current message is ", JSON.stringify(tree.root.message)); console.log("Number of children: ", tree.root.children.length); }); // Update the tree after 5 seconds setTimeout(() => { const newMessage = `Message from client ${Math.random().toFixed(2)}`; tree.root.message = newMessage; const newChild = new MyTreeNode({ message: `Another child ${Math.random().toFixed(2)}`, timestamp: Date.now(), children: [] }); tree.root.children.insertAtEnd(newChild); console.log(`Updated tree message to: ${newMessage}`); }, 5000); } startFluidClient().catch(console.error);
Debug
Known issues
breakingThe `minVersionForCollab` property is now a non-optional requirement in Fluid Framework client configurations, necessitating explicit specification when creating or loading containers.
fix
Ensure that `minVersionForCollab` is explicitly set within your container configuration object, typically when calling `createContainer()` or `getContainer()` via a service client. A common value is `1` for basic scenarios.
affects: >=2.93.0
breakingThe `@fluidframework/react` package, used for integrating Fluid content into React applications, no longer supports CommonJS (CJS) imports. It is now exclusively an ECMAScript Module (ESM).
fix
Migrate your React-based Fluid applications to use ECMAScript Modules (ESM) for imports. This generally involves setting `"type": "module"` in your `package.json` and ensuring your build system is configured to output ESM.
affects: >=2.90.0
breakingThe `cleared` event for `IDirectory` (and potentially other similar DDSes) now includes a `path` parameter in its signature, which may affect existing event listeners.
fix
Update your event listener signatures for the `IDirectory.cleared` event to accommodate the newly added `path` parameter.
affects: >=2.81.0
breaking`LatestMap`, a specific type of Distributed Data Structure, has removed support for number keys.
fix
Refactor your code to avoid using number keys directly in `LatestMap`. Convert number keys to strings before using them, or consider migrating to `SharedTree` if structured data with numeric identifiers is a core requirement.
affects: >=2.80.0
deprecated`SharedMap` is now considered a legacy Distributed Data Structure (DDS) as of Fluid Framework version 2.0. While still functional, it is not recommended for new development.
fix
For all new development and for migrating existing `SharedMap` instances, it is strongly recommended to use `SharedTree` instead, as it offers enhanced capabilities, better type safety, and is the actively developed DDS for collaborative data modeling.
affects: >=2.0.0
gotchaFluid Framework APIs are segmented by their stability level (public, beta, alpha, legacy) and require importing from specific package subpaths (e.g., `fluid-framework`, `fluid-framework/beta`, `fluid-framework/alpha`).
fix
Always ensure you are importing APIs from their correct subpath according to their stability level. Using unstable APIs carries risks and requires a more constrained version range (`~`) in your `package.json`.
affects: *
gotchaWhen declaring dependencies in `package.json`, use a `^` (caret) version range for public Fluid Framework APIs. However, for unstable (beta or alpha) APIs, a more constrained `~` (tilde) version range is recommended to minimize exposure to unannounced breaking changes.
fix
Configure your `package.json` dependencies with `"fluid-framework": "^x.y.z"` for public APIs and `"fluid-framework/beta": "~x.y.z"` for beta/alpha APIs to manage stability risks effectively.
affects: *
Errors
Common errors & fixes
Error: minVersionForCollab must be a non-negative number. Received: undefined
`minVersionForCollab` is missing from the container configuration object.
fix
Add `{ minVersionForCollab: 1 }` or an appropriate version to your `containerSchema` when calling `client.createContainer()` or `client.getContainer()`.
TypeError: require is not a function in ES module scope
Attempting to use `require()` for ESM-only Fluid Framework client packages (e.g., `@fluidframework/react`) in a CommonJS environment.
fix
Configure your project for ECMAScript Modules (ESM) by setting `"type": "module"` in your `package.json` and using `import` statements.
Property 'TreeAlpha' does not exist on type 'typeof import("fluid-framework")'.
Attempting to import a beta or alpha API directly from the root `fluid-framework` package instead of its specific subpath.
fix
Import beta APIs from `fluid-framework/beta` and alpha APIs from `fluid-framework/alpha`. For example: `import { TreeAlpha } from 'fluid-framework/alpha';`.
Type 'number' is not assignable to type 'string'.
Attempting to use a number as a key in a `LatestMap` instance after Fluid Framework v2.80.
fix
Convert number keys to strings before using them in `LatestMap`, or refactor to use `SharedTree` for structured data where numeric identifiers can be modeled differently.
Upgrade
Version history
2.93.0latest on npm
Audit
Dependencies
@fluidframework/azure-clientoptionalRequired to connect to Azure Fluid Relay service.
@fluidframework/tinylicious-clientoptionalRequired for local development and testing with Tinylicious service.
@fluidframework/odsp-clientoptionalRequired to connect to OneDrive/SharePoint Fluid services (currently in Beta).
@fluidframework/reactoptionalProvides React hooks and components for integrating Fluid content into React applications.
@fluidframework/app-insights-loggeroptionalRoutes Fluid telemetry to Azure Application Insights.
Agent activity
8 hits · last 30 days
node
8
Resources
fluid-framework — npm install fluid-framework · libregistry