Skip to main content
Fanfare has three public SDK paths. Choose the package set that matches how much UI ownership your application needs.
PathInstallUse when
React components@fanfare-io/fanfare-sdk-core and @fanfare-io/fanfare-sdk-reactYou use React and want the supported ExperienceWidget, hooks, slots, and styles.
Core SDK@fanfare-io/fanfare-sdk-coreYou want to render every state from JourneyView with your own UI.
Web components@fanfare-io/fanfare-sdk-core and @fanfare-io/fanfare-sdk-solidYou 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
Register the custom elements once: 
<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