@growth-rail/react

The Official Growth Rail React SDK. Easily integrate referral programs, track user growth, and display referral dashboards in your React applications.

🚀 Features

• Context-based Initialization: Seamless setup with GrowthRailProvider.
• Hooks for Ease of Use: Access the SDK anywhere with the useGrowthRail hook.
• Built-in UI Components: Drop-in widgets like ReferralDashboard to get started instantly.
• Fully Type-Safe: Written in TypeScript with complete definition support.
• Small Footprint: Optimized for performance and minimal bundle size.

📦 Installation

This package requires @growth-rail/core as a dependency and react as a peer dependency.

# npm
npm install @growth-rail/react @growth-rail/core

# yarn
yarn add @growth-rail/react @growth-rail/core

# pnpm
pnpm add @growth-rail/react @growth-rail/core

🛠 Usage

1. Wrap your App with GrowthRailProvider

Initialize the SDK at the root of your application. Provide your Project Secret Key and optionally a userId if the user is already authenticated.

import { GrowthRailProvider } from '@growth-rail/react';

function App() {
  return (
    <GrowthRailProvider 
      projectSecretKey="your_project_secret_key_here" 
      userId="user_123" // Optional: initialize for a specific user
      debug={true}      // Enable verbose console logging
    >
      <your-application-code />
    </GrowthRailProvider>
  );
}

2. Track Events and Get User Info

Use the useGrowthRail hook in any child component to track events or initialize users.

import { useGrowthRail } from '@growth-rail/react';

export function ActionButton() {
  const { trackRewardEvent, isLoading } = useGrowthRail();

  const handleAction = async () => {
    await trackRewardEvent('purchase_completed');
    console.log('Action tracked!');
  };

  return (
    <button onClick={handleAction} disabled={isLoading}>
      {isLoading ? 'Processing...' : 'Complete Action'}
    </button>
  );
}

3. Display the Referral Dashboard

Use the ReferralDashboard component to provide a white-labeled UI where users can see their referral link and rewards.

import { ReferralDashboard } from '@growth-rail/react';

export function DashboardPage() {
  return (
    <div style={{ padding: '20px' }}>
      <h1>My Rewards</h1>
      <ReferralDashboard 
        title="Invite your friends and earn!" 
        onLinkCopied={() => alert('Link copied!')}
      />
    </div>
  );
}

📖 API Reference

useGrowthRail()

The main hook for interacting with the Growth Rail SDK.

Methods:

• initAppUser(userId): Initializes the SDK for a specific user.
• trackRewardEvent(eventName?): Tracks a custom event for attribution and rewards.
• showReferralDashboard(options?): Programmatically triggers the referral dashboard modal.
• showFloatingButton(options): Displays the floating referral trigger button.
• hideFloatingButton(): Removes the floating referral trigger button.

State:

• isLoading: Boolean indicating if an async operation is pending.
• error: The last error that occurred (if any).

ReferralDashboard

An inline dashboard component for your application.

| Prop | Type | Description | | :--- | :--- | :--- | | title | string | Optional title for the dashboard. | | onLinkCopied | () => void | Callback when the referral link is copied. |

For full documentation, visit docs.growthrail.com.

📄 License

MIT © Growth Rail