Installation

Everything needed before the first widget renders: the package, the provider, and one Content Security Policy rule that trips people up.

Install the package

npm

npm install @roastnest/react

yarn

yarn add @roastnest/react

pnpm

pnpm add @roastnest/react

The package ships both CommonJS and ESM builds along with TypeScript declarations, so no additional @types package is needed.

React and React DOM are peer dependencies at >=16.8.0 — the widgets are hook-based, so anything from the hooks release onward works, including React 19. The SDK bundles its own floating-element positioning, screenshot capture and device detection, so there is nothing else to install.

Add the provider

RoastnestProvider is the only required wrapper. It carries the mode, the project ID and an optional theme down to every widget. Widgets throw if they are rendered outside it.

Cloud

app.tsx

import { RoastnestProvider } from "@roastnest/react";

export default function App() {
  return (
    <RoastnestProvider mode="cloud" projectId="YOUR_PROJECT_ID">
      <YourMainApp />
    </RoastnestProvider>
  );
}

Self-hosted

projectId is optional here — it is only used to tag the payloads handed to your own callbacks.

app.tsx

import { RoastnestProvider } from "@roastnest/react";

export default function App() {
  return (
    <RoastnestProvider mode="self-hosted">
      <YourMainApp />
    </RoastnestProvider>
  );
}

Provider props

Prop	Type	Default	Description
`mode`	`"cloud" \| "self-hosted"`	`"cloud"`	Where submissions go. Also determines which widget props are required, and which are rejected at compile time.
`projectId`	`string`	—	Your project's identifier from the dashboard. Required in cloud mode, optional in self-hosted.
`theme`	`WidgetTheme`	—	Colors, radius and font applied to both widgets. See Theming.
`children`required	`ReactNode`	—	Your application tree.

Content Security Policy

If your site sends a Content-Security-Policy header, the widget cannot reach the Roastnest API unless you allow it in connect-src. Without this rule the widget renders fine and then fails silently on submit.

Content-Security-Policy

connect-src 'self' https://api.roastnest.com;

One origin covers everything

That single entry is enough for the whole SDK, screenshot uploads included. You do not need to allow an S3 bucket or a CDN origin separately.

What the package exports

Available exports

import {
  RoastnestProvider,
  FeedbackWidget,
  ReferralWidget,
  ReferralLifecycle,
  useFeedback,
  useReferral,
  ReferralAPI,
} from "@roastnest/react";

import type {
  RoastnestProviderProps,
  FeedbackWidgetProps,
  FeedbackCustomizeProps,
  ReferralWidgetProps,
  ReferralEventPayload,
  ConversionEvent,
} from "@roastnest/react";

Verify the install

Render a FeedbackWidget and open the browser console. The SDK logs a descriptive error rather than crashing when something is misconfigured — a missing project ID in cloud mode, or a missing onFormSubmit in self-hosted mode, both report themselves there. If the console is quiet and the trigger button is visible, you are set up correctly.

Still stuck? Troubleshooting lists the failure modes worth checking first.