> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fanfare.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Fanfare SDK package for your integration path.

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:

```bash theme={null}
pnpm add @fanfare-io/fanfare-sdk-core @fanfare-io/fanfare-sdk-react motion
```

Equivalent commands:

```bash theme={null}
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:

```tsx theme={null}
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`.

```tsx theme={null}
import { useExperienceJourney } from "@fanfare-io/fanfare-sdk-react";
```

## Core SDK

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

```bash theme={null}
pnpm add @fanfare-io/fanfare-sdk-core
```

Initialize once and read the public journey view:

```ts theme={null}
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:

```bash theme={null}
pnpm add @fanfare-io/fanfare-sdk-core @fanfare-io/fanfare-sdk-solid solid-js
```

Register the custom elements once:

```html theme={null}
<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:

```html theme={null}
<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:

```ts theme={null}
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:

```tsx theme={null}
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](/getting-started/quickstart) - Build the first React integration.
* [Configuration](/getting-started/configuration) - Set credentials, copy, and theme.
* [Choose Your Path](/sdk/choose-your-path) - Compare core, React, and web component paths.