Skip to main content

​
Installation

Fanfare provides official SDK packages for different frameworks. Choose the installation that matches your project setup.

​
Package Overview

Packagenpm NameDescription
Core SDK@fanfare/sdkFramework-agnostic core functionality
React SDK@fanfare/reactReact hooks, components, and provider
SolidJS SDK@fanfare/solidSolidJS primitives and components
The React and SolidJS packages depend on the core SDK and install it automatically.

​
React

​
Installation

npm install @fanfare/react motion
Or with other package managers: 
# Yarn
yarn add @fanfare/react motion

# pnpm
pnpm add @fanfare/react motion

# Bun
bun add @fanfare/react motion

​
Requirements

  • React 18.0.0 or later (React 19 is also supported)
  • ReactDOM 18.0.0 or later
  • Motion 12.0.0 or later (for animations)

​
Exports

The React package provides: 
// Provider
import { FanfareProvider } from "@fanfare/react";

// Hooks
import {
  useFanfare,
  useExperienceJourney,
  useQueue,
  useDraw,
  useAuction,
  useWaitlist,
  useTimedRelease,
  useFanfareAuth,
} from "@fanfare/react";

// Pre-built widgets
import { QueueWidget, DrawWidget, AuctionWidget, WaitlistWidget } from "@fanfare/react";

// Composition components
import { AdmittedView, EndedView, ErrorView, AuthForm } from "@fanfare/react";

// Primitives
import { Button, Card, Input, QueuePosition } from "@fanfare/react";

// Styles (optional - for default widget styling)
import "@fanfare/react/styles";

​
TypeScript Support

The React SDK is written in TypeScript and includes type definitions. No additional @types packages are required. 
import type { FanfareProviderProps, QueueWidgetProps, UseDrawReturn } from "@fanfare/react";

​
SolidJS

​
Installation

npm install @fanfare/solid @fanfare/sdk motion
Or with other package managers: 
# Yarn
yarn add @fanfare/solid @fanfare/sdk motion

# pnpm
pnpm add @fanfare/solid @fanfare/sdk motion

​
Requirements

  • SolidJS 1.8.0 or later
  • Motion 12.0.0 or later (for animations)

​
Exports

The SolidJS package provides: 
// Provider
import { FanfareProvider, useFanfare } from "@fanfare/solid";

// Hooks
import {
  useExperienceJourney,
  useQueue,
  useDraw,
  useAuction,
  useWaitlist,
  useTimedRelease,
  useAuth,
} from "@fanfare/solid";

// Pre-built widgets
import { QueueWidget, DrawWidget, AuctionWidget, WaitlistWidget } from "@fanfare/solid";

// Web components registration
import { registerWebComponents } from "@fanfare/solid";

// Styles
import "@fanfare/solid/styles";

​
Web Components

The SolidJS SDK supports web component registration for use outside of SolidJS applications: 
import { registerWebComponents } from "@fanfare/solid";

// Register all Fanfare web components
registerWebComponents();
Then use them as custom elements: 
<fanfare-queue experience-id="exp_123"></fanfare-queue>

​
Vanilla JavaScript (Core SDK)

​
Installation

npm install @fanfare/sdk
Or with other package managers: 
# Yarn
yarn add @fanfare/sdk

# pnpm
pnpm add @fanfare/sdk

​
Requirements

  • A modern browser with ES2020 support
  • Valibot 1.1.0 or later (peer dependency for validation)

​
Usage

import { init } from "@fanfare/sdk";

async function main() {
  const fanfare = await init({
    organizationId: "org_abc123",
    publishableKey: "pk_live_xyz789",
  });

  // Restore any existing session
  await fanfare.restore();

  // Create a guest session
  await fanfare.auth.guest();

  // Enter an experience
  const session = await fanfare.experiences.enter("exp_123");

  // Join a queue
  const result = await fanfare.queues.enter("queue_456");
  console.log("Position:", result.position);

  // Start polling for updates
  fanfare.queues.startPolling("queue_456");

  // Listen for admission
  fanfare.on("queue:admitted", (data) => {
    console.log("Admitted with token:", data.token);
    // Redirect to checkout
  });
}

main();

​
Exports

// Main init function
import { init } from "@fanfare/sdk";

// Types
import type { FanfareConfig, FanfareSDK, Queue, Draw, AuctionDetails, Session } from "@fanfare/sdk";

// Experience journey (state machine)
import { ExperienceJourney } from "@fanfare/sdk";

// Error handling
import { FanfareError, ErrorCodes, isFanfareError } from "@fanfare/sdk";

// Theme utilities
import { DefaultExperienceTheme, mergeExperienceTheme } from "@fanfare/sdk";

// Test utilities
import { createMockFanfareSDK } from "@fanfare/sdk/test-utils";

​
CDN Installation

For quick prototyping or non-bundled projects, you can load the SDK from a CDN: 
<script type="module">
  import { init } from "https://esm.sh/@fanfare/sdk@latest";

  const fanfare = await init({
    organizationId: "org_abc123",
    publishableKey: "pk_live_xyz789",
  });

  // Use the SDK...
</script>
CDN Usage: Using ESM from CDN services like esm.sh works for prototyping but is not recommended for production. Use a bundler for optimal performance and reliability.

​
Bundle Size

The Fanfare SDK is designed to be lightweight:
PackageSize (gzipped)
@fanfare/sdk (core)~34 KB
@fanfare/react~45 KB (includes core)
@fanfare/solid~40 KB (includes core)
The SDK supports tree-shaking, so unused modules are not included in your final bundle.

​
ESM Only

All Fanfare packages are ESM-only. If your project uses CommonJS, you may need to configure your bundler to handle ESM dependencies.

​
Vite

Vite handles ESM natively. No additional configuration is required.

​
Next.js

Next.js supports ESM packages in both the App Router and Pages Router: 
// app/layout.tsx or pages/_app.tsx
import { FanfareProvider } from "@fanfare/react";

​
Webpack

For Webpack 5, ESM packages work by default. For Webpack 4, you may need to configure the resolve.fullySpecified option: 
// webpack.config.js
module.exports = {
  resolve: {
    fullySpecified: false,
  },
};

​
Peer Dependencies

​
Valibot

The core SDK requires Valibot for runtime validation: 
npm install valibot
If you are using the React or SolidJS packages, Valibot is included as a transitive dependency.

​
Motion

The React and SolidJS packages use Motion for animations: 
npm install motion
Motion is a peer dependency because:
  1. It allows you to share a single instance across your app
  2. You can configure motion settings globally
  3. It reduces bundle size when you already use motion elsewhere
If you do not want animations, install motion anyway but configure the SDK to disable animations (see Configuration).

​
Verifying Installation

After installation, verify the SDK is working: 
import { FanfareProvider, useFanfare } from "@fanfare/react";

function DebugComponent() {
  const fanfare = useFanfare();
  console.log("Fanfare SDK loaded:", fanfare);
  return <div>SDK Ready</div>;
}

function App() {
  return (
    <FanfareProvider organizationId="org_test123" publishableKey="pk_test_xyz789">
      <DebugComponent />
    </FanfareProvider>
  );
}
Check your browser console. You should see the SDK object logged without errors.

​
Next Steps