> ## 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.

# Configuration

> Configure Fanfare SDK credentials, widgets, and public customization surfaces.

Fanfare configuration starts with three values:

| Value            | Purpose                                              |
| ---------------- | ---------------------------------------------------- |
| `organizationId` | Your Fanfare organization ID from the dashboard.     |
| `publishableKey` | A browser-safe publishable key for your integration. |
| `experienceId`   | The experience your page should render.              |

Keep secret keys on your server. Client SDK integrations should use publishable keys only.

## React Provider

Most React apps configure Fanfare once near the route or app area that renders the experience.

```tsx theme={null}
import { 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"
      locale="en"
    >
      <ProductLaunchPage />
    </FanfareProvider>
  );
}
```

`FanfareProvider` initializes the core SDK, restores local session state by default, and provides SDK access to components and hooks below it.

Common provider props:

| Prop               | Use for                                                  |
| ------------------ | -------------------------------------------------------- |
| `organizationId`   | Required organization ID.                                |
| `publishableKey`   | Required browser-safe key.                               |
| `autoRestore`      | Restore local session on mount. Defaults to `true`.      |
| `autoResume`       | Resume known journeys after restore. Defaults to `true`. |
| `loadingComponent` | UI shown while the provider initializes.                 |
| `locale`           | Locale for built-in component text.                      |
| `translations`     | Partial copy overrides.                                  |
| `debug`            | Development troubleshooting only.                        |

See [Configuration Reference](/sdk/reference/configuration) for the full public option list.

## ExperienceWidget

Configure the journey UI with `ExperienceWidget`.

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

export function ProductLaunchPage() {
  return (
    <ExperienceWidget
      experienceId="exp_123"
      autoStart
      checkoutUrl="/checkout"
      variant="clean"
    />
  );
}
```

Common widget props:

| Prop                | Use for                                                            |
| ------------------- | ------------------------------------------------------------------ |
| `experienceId`      | Required experience ID.                                            |
| `autoStart`         | Start the journey when the widget is ready.                        |
| `checkoutUrl`       | Default destination after a grant.                                 |
| `onGranted`         | Custom server handoff or app routing after a grant.                |
| `slots`             | Override specific journey states.                                  |
| `theme`             | Per-widget theme values.                                           |
| `variant`           | Supported widget visual variant.                                   |
| `accessCode`        | Provide an access code when your page already has one.             |
| `autoEnterWaitlist` | Enter waitlist automatically when that public action is available. |

Use `onGranted` when checkout needs a trusted handoff:

```tsx theme={null}
<ExperienceWidget
  experienceId="exp_123"
  autoStart
  onGranted={async (admissionGrant) => {
    await fetch("/api/fanfare/admission", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ admissionGrant }),
    });
    window.location.assign("/checkout");
  }}
/>
```

## Copy And Theme

Use provider-level `locale` and `translations` for shared copy. Use widget `theme`, `variant`, and `slots` for per-page customization.

```tsx theme={null}
<FanfareProvider
  organizationId="org_123"
  publishableKey="pk_live_123"
  locale="en"
  translations={{
    "queue.enter": "Join the launch",
    "granted.cta": "Continue",
  }}
>
  <ExperienceWidget
    experienceId="exp_123"
    variant="rounded"
    theme={{
      primary: "#0F766E",
      fontFamily: "Inter, system-ui, sans-serif",
    }}
  />
</FanfareProvider>
```

For targeted UI ownership, use slots:

```tsx theme={null}
<ExperienceWidget
  experienceId="exp_123"
  slots={{
    granted: ({ grant, expiresAt }) => (
      <CheckoutPanel
        admissionGrant={grant}
        admissionGrantExpiresAt={expiresAt}
      />
    ),
  }}
/>
```

## Core SDK

Use the core SDK when your application owns every screen.

```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");

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

Call `sdk.destroy()` when the application area that owns the SDK permanently unmounts.

## Web Components

Register web components once before rendering custom elements.

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

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

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

Listen for granted events when the host page needs a custom handoff:

```html theme={null}
<script>
  const widget = document.querySelector("fanfare-experience-widget");

  widget.addEventListener("fanfare-granted", async (event) => {
    await fetch("/api/fanfare/admission", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ admissionGrant: event.detail.grant }),
    });

    window.location.assign("/checkout");
  });
</script>
```

Avoid logging admission grants or raw journey snapshots to third-party tools.

## Environment Variables

Use framework-supported public environment variables for browser credentials.

```bash theme={null}
NEXT_PUBLIC_FANFARE_ORG_ID=org_123
NEXT_PUBLIC_FANFARE_PUBLISHABLE_KEY=pk_live_123
```

```tsx theme={null}
<FanfareProvider
  organizationId={process.env.NEXT_PUBLIC_FANFARE_ORG_ID!}
  publishableKey={process.env.NEXT_PUBLIC_FANFARE_PUBLISHABLE_KEY!}
>
  <ProductLaunchPage />
</FanfareProvider>
```

Common public prefixes:

| Framework        | Prefix         |
| ---------------- | -------------- |
| Next.js          | `NEXT_PUBLIC_` |
| Vite             | `VITE_`        |
| Astro            | `PUBLIC_`      |
| Create React App | `REACT_APP_`   |

## Development And Production

Use test credentials for development and live credentials for production.

```tsx theme={null}
const isProduction = process.env.NODE_ENV === "production";

<FanfareProvider
  organizationId={process.env.NEXT_PUBLIC_FANFARE_ORG_ID!}
  publishableKey={
    isProduction
      ? process.env.NEXT_PUBLIC_FANFARE_LIVE_KEY!
      : process.env.NEXT_PUBLIC_FANFARE_TEST_KEY!
  }
>
  <ProductLaunchPage />
</FanfareProvider>;
```

The SDK chooses its supported public environment by default. Do not set environment or API URL overrides unless your Fanfare contact explicitly asks you to. Only enable debug logging during guided troubleshooting.

## Next Steps

* [Quickstart](/getting-started/quickstart) - Render the first experience.
* [Testing](/getting-started/testing) - Test public journey states.
* [Configuration Reference](/sdk/reference/configuration) - Review the full public option list.