Installation

Get started with Fluid Framework by installing the necessary packages and setting up your development environment.

Prerequisites

Before installing Fluid Framework, ensure you have:

• Node.js version 18 or higher
• npm, yarn, or pnpm package manager
• A modern browser (Chrome, Firefox, Safari, Edge)

Package Installation

Fluid Framework is distributed as multiple npm packages. Install the core packages you need:

Essential Packages

# Core Fluid packages
npm install @fluidframework/azure-client
npm install @fluidframework/map
npm install @fluidframework/sequence

# For local development
npm install @fluidframework/tinylicious-client

Development Dependencies

# TypeScript definitions (if using TypeScript)
npm install --save-dev @fluidframework/build-tools

Service Setup

Local Development with Tinylicious

For local development, use Tinylicious - a minimal Fluid service:

# Install Tinylicious globally
npm install -g @fluidframework/tinylicious

# Start the local service
npx tinylicious

The service will run on http://localhost:7070 by default.

Azure Fluid Relay Service

For production applications, configure Azure Fluid Relay:

1. Create an Azure Fluid Relay resource in the Azure portal
2. Get your tenant ID and primary key
3. Configure your application with these credentials

import { AzureClient, AzureClientProps } from "@fluidframework/azure-client";

const clientProps: AzureClientProps = {
    connection: {
        tenantId: "YOUR_TENANT_ID",
        tokenProvider: new InsecureTokenProvider("YOUR_PRIMARY_KEY", { id: "userId" }),
        endpoint: "https://YOUR_SERVICE_ENDPOINT",
        type: "remote",
    },
};

const client = new AzureClient(clientProps);

Project Structure

Set up your project structure for Fluid applications:

my-fluid-app/
├── src/
│   ├── fluid/
│   │   ├── containerSchema.ts    # Define your data structures
│   │   ├── fluidService.ts       # Service configuration
│   │   └── dataObjects.ts        # Custom data objects
│   ├── components/               # React/UI components
│   └── app.ts                   # Main application entry
├── package.json
└── tsconfig.json                # TypeScript configuration

TypeScript Configuration

Configure TypeScript for optimal Fluid development:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM"],
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Environment Variables

Create a .env.local file for local development:

# Local Tinylicious service
FLUID_CLIENT_TYPE=tinylicious
FLUID_SERVICE_URL=http://localhost:7070

# Or Azure Fluid Relay for production
# FLUID_CLIENT_TYPE=azure
# FLUID_TENANT_ID=your-tenant-id
# FLUID_PRIMARY_KEY=your-primary-key
# FLUID_SERVICE_ENDPOINT=https://your-endpoint

Verification

Verify your installation by creating a simple test:

import { TinyliciousClient } from "@fluidframework/tinylicious-client";
import { SharedMap } from "@fluidframework/map";

// Create a client
const client = new TinyliciousClient();

// Define container schema
const containerSchema = {
    initialObjects: {
        myMap: SharedMap,
    },
};

// Test connection
async function testInstallation() {
    try {
        const { container } = await client.createContainer(containerSchema);
        console.log("Fluid Framework installed successfully!");
        console.log("Container ID:", container.id);
    } catch (error) {
        console.error("Installation verification failed:", error);
    }
}

testInstallation();

Common Installation Issues

Node.js Version Issues

Ensure you're using Node.js 18 or higher:

node --version  # Should be v18.0.0 or higher

Package Resolution Errors

Clear npm cache and reinstall:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

CORS Issues in Development

If running into CORS issues with Tinylicious, start it with CORS enabled:

npx tinylicious --cors

Next Steps

Now that Fluid Framework is installed:

1. Build Your First App - Create a simple collaborative application
2. Explore Examples - See working code samples
3. Learn Core Concepts - Understand Fluid's architecture
4. Read User Guides - Dive deeper into specific topics

Package Reference

Core Client Packages

• @fluidframework/azure-client - Azure Fluid Relay client
• @fluidframework/tinylicious-client - Local development client
• @fluidframework/fluid-static - Simplified client APIs

Distributed Data Structures

• @fluidframework/map - SharedMap data structure
• @fluidframework/sequence - SharedString and SharedNumberSequence
• @fluidframework/matrix - SharedMatrix for 2D data
• @fluidframework/tree - Experimental tree data structure

Utilities and Tools

• @fluidframework/build-tools - Build and development utilities
• @fluidframework/test-utils - Testing utilities
• @fluidframework/devtools - Browser debugging extension