npm package: @stare/react-bindings
Description: React bindings for Stare Analytics SDK
Latest version: 0.1.9

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

```bash
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:

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

function App() {
  return (
    <StareProvider 
      key="your-api-key"
      user={{
        email: 'user@example.com',
        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:

```tsx
<StareProvider 
  key="your-api-key"
  user={{ email: 'user@example.com' }}
  loadingComponent={<div>Loading analytics...</div>}
>
  <YourApp />
</StareProvider>
```

### Using the Hook

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

```tsx
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:

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

const client = new StareClient('your-api-key', {
  email: 'user@example.com'
}, {
  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

```typescript
{
  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

```tsx
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:

```typescript
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