@roastnest/react

The official React SDK for Roastnest. A unified, lightweight, and customizable client-side package that includes an interactive Feedback/Bug Reporting Widget, a Referral Program Widget, and Conversion Tracking APIs.

Table of Contents

• Features
• Installation
• Getting Started
• Modes
  • Self-Hosted Mode
  • Cloud Mode
• Feedback Widget
  • Basic Setup
  • useFeedback Hook
  • Feedback Customization Props
• Referral Widget
  • Basic Setup
  • Auto-generated Referral Links & Validation
  • useReferral Hook & Conversion Tracking
  • Referral Lifecycle Visualizer
• License

Features

• 🖱️ Visual Element Selector: Highlight and select any DOM element to provide contextual feedback.
• 📸 Auto Screenshots: Capture selected element or full-page screenshots using html2canvas-pro.
• 🤝 Referral & Rewards Widget: Modern invite cards with clipboard-copying and Web Share API integration.
• 🔗 Auto-Generated Referrals: Client-side referral code generation and persistence via localStorage.
• 🛡️ Hostname Validation: Automatically validates referralLink domain matching to avoid broken referral loops.
• 🔌 Graceful Degradation: Catches configuration issues internally and degrades safely without crashing your React tree.
• ⚙️ Dual Modes: Support for complete control under Self-Hosted (callbacks) or Cloud (remote Roastnest server).

Installation

npm install @roastnest/react

or

yarn add @roastnest/react

Content Security Policy

If your site sends a Content-Security-Policy header, allow the Roastnest API in connect-src — the widget cannot reach it otherwise, and feedback submission will fail:

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

That single origin covers everything the widget does, including screenshot uploads. No S3 or CDN origin is required.

Getting Started

To initialize the SDK, wrap your application inside the RoastnestProvider component.

Compile-time Mandatory Props by Mode

You can enforce compile-time typings on both <FeedbackWidget> and <ReferralWidget> by passing the mode prop directly to them. This ensures you do not miss mandatory props:

• Self-Hosted Mode:
  • <FeedbackWidget> requires onFormSubmit (custom form handler) and optionally accepts customize.
  • <ReferralWidget> requires referralLink (absolute URL matching your hostname) and onEvent (custom event tracking callback). It accepts all custom content, theme, buttons, and copying props.
• Cloud Mode:
  • All content, customization, and submission/event callbacks are loaded directly from the Roastnest Cloud server.
  • Specifying customization props (customize, onFormSubmit for feedback; or appName, theme, referralLink, onEvent, etc. for referrals) is strictly forbidden at compile-time to prevent configurations from conflicting with the server-defined settings. Only advanced state controls (like visible, defaultOpen, closeOnBackdropClick) are allowed.

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

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

Modes

@roastnest/react operates in two modes:

Self-Hosted Mode

Provides full offline capabilities, allowing you to completely handle submit and event tracking callbacks in your own codebase without sending any data to Roastnest servers.

• Provider setup: <RoastnestProvider mode="self-hosted" />

Cloud Mode

Hooks directly into Roastnest servers, automatically syncing feedback, uploads, screenshots, and referral conversions to your dashboard.

• Provider setup: <RoastnestProvider mode="cloud" projectId="your_project_id" />

Feedback Widget

The feedback widget adds a floating action button on your page that triggers element selection, email collection, and feedback reporting.

Basic Setup

Simply place the <FeedbackWidget /> anywhere under the provider:

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

function Layout() {
  return (
    <div>
      <FeedbackWidget />
    </div>
  );
}

useFeedback Hook

Control the feedback overlay programmatically from any component.

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

function CustomButton() {
  const { isFeedbackOpen, toggleFeedback, avoidElementClassName } = useFeedback();

  return (
    <button onClick={toggleFeedback} className={avoidElementClassName}>
      {isFeedbackOpen ? "Close Feedback" : "Submit Bug / Feedback"}
    </button>
  );
}

Feedback Customization Props

Pass the customize object to customize the feedback form and notification bubbles.

| Property | Type | Description | |---|---|---| | form.messageInput.placeholder | string | Placeholder for the text area | | form.submitButton.label | string | Submit button label | | notifications.enable | boolean | Enable or disable periodic bottom notifications | | notifications.messages | Array | List of notification messages and types |

Referral Widget

The referral widget renders a sleek dashboard to refer friends and invite others using clipboard copy options or native share actions.

Basic Setup

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

function InvitePage() {
  return (
    <ReferralWidget
      referralLink="https://myapp.com/invite"
      appName="My Awesome App"
      referrerRewardAmount="$20"
      refereeRewardAmount="$10"
      onEvent={(payload) => console.log("Referral Event:", payload)}
    />
  );
}

Auto-generated Referral Links & Validation

• Auto-Generated Referrals: In self-hosted mode, the SDK automatically generates a secure unique referral code for each user and stores it persistently in the browser's localStorage (e.g. roastnest_my_referral_code). In cloud mode, both the referral code and referral link are fetched directly from the Roastnest cloud server on mount.
• Auto-Appending Parameter: In self-hosted mode, when you provide referralLink="https://myapp.com/invite", the SDK will automatically append the generated referral code as a query param (e.g., https://myapp.com/invite?ref=AYUSH123).
• Domain Matching: For safety in self-hosted mode, the domain of the referralLink must match window.location.hostname. If they do not match, the widget will log a console.error and degrade gracefully by returning null to avoid breaking the user's webpage. Domain matching is not required in cloud mode since configurations are pre-validated on your Roastnest dashboard.

useReferral Hook & Conversion Tracking

To track successful referral conversions (e.g., a friend signed up, subscribed, or performed an action), use the headless hook useReferral:

import React, { useEffect } from "react";
import { useReferral } from "@roastnest/react";

export function SignupSuccessPage() {
  const { trackConversion, referralCode, hasReferral } = useReferral();

  useEffect(() => {
    if (hasReferral) {
      // Trigger a conversion event
      trackConversion({ event: "signup" });
    }
  }, [hasReferral]);

  return <h1>Thank you for signing up! (Referral Code Detected: {referralCode})</h1>;
}

Referral Lifecycle Visualizer

The SDK contains a built-in visualizer to simulate and test your referral lifecycle stages (Shared -> Clicked -> Saved -> Action -> Attributed -> Reward Approved).

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

function DebugPanel() {
  return (
    <div style={{ padding: 20, border: "1px dashed gray" }}>
      <h3>Test Referral Stages Simulator</h3>
      <ReferralLifecycle />
    </div>
  );
}

License

MIT © RoastNest