@stare/react-bindings

React bindings for the Stare Analytics SDK. This package provides React components and hooks to easily integrate Stare analytics into your React applications.

Installation

npm install @stare/react-bindings
# or
yarn add @stare/react-bindings
# or
pnpm add @stare/react-bindings

Usage

Basic Setup with StareProvider

Wrap your application with the StareProvider component:

import { StareProvider } from '@stare/react-bindings';

function App() {
  return (
    <StareProvider 
      key="your-api-key"
      user={{
        email: '[email protected]',
        userID: 'user-123',
        properties: { plan: 'premium' }
      }}
      options={{
        autocapture: { page: true, click: true }
      }}
    >
      <div>Your App Content</div>
    </StareProvider>
  );
}

With Loading Component

You can display a loading component while the client initializes:

<StareProvider 
  key="your-api-key"
  user={{ email: '[email protected]' }}
  loadingComponent={<div>Loading analytics...</div>}
>
  <YourApp />
</StareProvider>

Using the Hook

Use the useStareClient hook to access the client and send events:

import { useStareClient } from '@stare/react-bindings';

function MyComponent() {
  const { client, send, isLoading } = useStareClient();

  const handleClick = () => {
    send('Button Clicked', { 
      buttonName: 'Subscribe',
      location: 'header' 
    });
  };

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <button onClick={handleClick}>
      Subscribe
    </button>
  );
}

Advanced: Using Your Own Client Instance

You can also pass a pre-configured client instance:

import { StareClient } from '@stare/js-client';
import { StareProvider } from '@stare/react-bindings';

const client = new StareClient('your-api-key', {
  email: '[email protected]'
}, {
  autocapture: { page: true, click: false }
});

function App() {
  return (
    <StareProvider client={client}>
      <YourApp />
    </StareProvider>
  );
}

API Reference

StareProvider

The main provider component that initializes and manages the Stare client.

Props

Configuration-based (recommended):

• key (string, required): Your Stare API key
• user (StareUser, required): User information
  • email (string, required): User's email address
  • userID (string, optional): User's unique identifier
  • properties (object, optional): Additional user properties
• options (StareOptions, optional): SDK configuration options
  • autocapture.page (boolean): Enable page view tracking (default: true)
  • autocapture.click (boolean): Enable click tracking (default: true)
  • flush.interval (number): Event flush interval in ms (default: 10000)
  • flush.threshold (number): Event batch size threshold (default: 50)
  • session.duration (number): Session duration in ms (default: 1800000)
  • session.storage (boolean): Enable session storage (default: true)
• children (ReactNode): Your application components
• loadingComponent (ReactNode, optional): Component to show while initializing

Client-based:

• client (StareClient, required): Pre-configured Stare client instance
• children (ReactNode): Your application components
• loadingComponent (ReactNode, optional): Component to show while initializing

useStareClient

Hook to access the Stare client and send events.

Returns

{
  client: StareClient;        // The Stare client instance
  send: (event: string, properties?: Record<string, unknown>) => void;  // Send an event
  isLoading: boolean;          // Whether the client is still initializing
}

Example

const { client, send, isLoading } = useStareClient();

// Send a custom event
send('Purchase Completed', { 
  amount: 99.99, 
  currency: 'USD',
  productId: 'prod-123'
});

// Access the full client
const userEmail = client.getUser().getEmail();

TypeScript Support

This package is written in TypeScript and includes full type definitions. All types are exported for your convenience:

import type { 
  StareProviderProps,
  StareContextValue,
  StareUser,
  StareOptions,
  StareClient
} from '@stare/react-bindings';

Best Practices

1. Place StareProvider high in your component tree - Typically at the root of your application
2. Initialize once - The provider handles client initialization and cleanup automatically
3. Use the hook for events - The useStareClient hook provides optimized event tracking
4. Handle loading states - Use the isLoading flag or loadingComponent prop for better UX

License

MIT