Installation

Fanfare has three public SDK paths. Choose the package set that matches how much UI ownership your application needs.

Path	Install	Use when
React components	`@fanfare-io/fanfare-sdk-core` and `@fanfare-io/fanfare-sdk-react`	You use React and want the supported `ExperienceWidget`, hooks, slots, and styles.
Core SDK	`@fanfare-io/fanfare-sdk-core`	You want to render every state from `JourneyView` with your own UI.
Web components	`@fanfare-io/fanfare-sdk-core` and `@fanfare-io/fanfare-sdk-solid`	You need a custom element for static HTML, CMS pages, or a non-React host.

All paths use the same journey model. You can start with a component path and move specific states to custom UI later.

React

Install the core SDK, React adapter, and animation peer dependency:

pnpm add @fanfare-io/fanfare-sdk-core @fanfare-io/fanfare-sdk-react motion

Equivalent commands:

npm install @fanfare-io/fanfare-sdk-core @fanfare-io/fanfare-sdk-react motion
yarn add @fanfare-io/fanfare-sdk-core @fanfare-io/fanfare-sdk-react motion
bun add @fanfare-io/fanfare-sdk-core @fanfare-io/fanfare-sdk-react motion

The React package has peer dependencies on react, react-dom, and motion. Use the provider and widget:

import {
  ExperienceWidget,
  FanfareProvider,
} from "@fanfare-io/fanfare-sdk-react";
import "@fanfare-io/fanfare-sdk-react/styles";

export function App() {
  return (
    <FanfareProvider
      organizationId="org_123"
      publishableKey="pk_live_123"
    >
      <ExperienceWidget experienceId="exp_123" autoStart checkoutUrl="/checkout" />
    </FanfareProvider>
  );
}

For custom React UI, import useExperienceJourney and render from the returned view.

import { useExperienceJourney } from "@fanfare-io/fanfare-sdk-react";

Core SDK

Install only the core package when your application owns the UI:

pnpm add @fanfare-io/fanfare-sdk-core

Initialize once and read the public journey view:

import initFanfare from "@fanfare-io/fanfare-sdk-core";
import type { JourneyView } from "@fanfare-io/fanfare-sdk-core/experiences";

const sdk = await initFanfare({
  organizationId: "org_123",
  publishableKey: "pk_live_123",
});

const journey = sdk.journeys.get("exp_123");

journey.view$.listen((view: JourneyView) => {
  renderJourney(view);
});

Render UI from JourneyView and call only actions exposed by the current view.

Web Components

Install the core SDK, Solid adapter, and Solid peer dependency:

pnpm add @fanfare-io/fanfare-sdk-core @fanfare-io/fanfare-sdk-solid solid-js

<script type="module">
  import { registerWebComponents } from "@fanfare-io/fanfare-sdk-solid";

  registerWebComponents({
    organizationId: "org_123",
    publishableKey: "pk_live_123",
  });
</script>

Then render the experience widget:

<fanfare-experience-widget
  experience-id="exp_123"
  auto-start
  checkout-url="/checkout"
></fanfare-experience-widget>

TypeScript and Modules

Fanfare SDK packages include TypeScript definitions and are ESM-only. Modern bundlers such as Vite, Next.js, Webpack 5, and Astro handle ESM packages without additional SDK configuration. Import public types from the package that owns the API:

import type { JourneyView } from "@fanfare-io/fanfare-sdk-core/experiences";
import type { ExperienceWidgetProps } from "@fanfare-io/fanfare-sdk-react";

No CDN Path

Use the npm packages with a bundler for production integrations. The public SDK docs do not define a separate CDN API surface.

Verify Installation

Use a minimal render before adding custom states:

import {
  ExperienceWidget,
  FanfareProvider,
} from "@fanfare-io/fanfare-sdk-react";
import "@fanfare-io/fanfare-sdk-react/styles";

export function FanfareSmokeTest() {
  return (
    <FanfareProvider organizationId="org_123" publishableKey="pk_test_123">
      <ExperienceWidget experienceId="exp_123" />
    </FanfareProvider>
  );
}

If the provider mounts and the widget renders a ready, loading, gated, participating, admitted, or unavailable state, the package install is working. Use test credentials and a test experience for local verification.

Next Steps

Quickstart - Build the first React integration.
Configuration - Set credentials, copy, and theme.
Choose Your Path - Compare core, React, and web component paths.

Getting Started

Core Concepts

Distribution Types

React

Core SDK

Web Components

TypeScript and Modules

No CDN Path

Verify Installation

Next Steps

​React

​Core SDK

​Web Components

​TypeScript and Modules

​No CDN Path

​Verify Installation

​Next Steps

React

Core SDK

Web Components

TypeScript and Modules

No CDN Path

Verify Installation

Next Steps