npm package: @struct-app/react
Description: ## Installation
Latest version: 0.2.1

# Struct React SDK

## Installation

```bash
 npm install --save @struct-app/react
```

## Setup

###  1. Create Struct Hooks and Context Provider

Use the `createStruct` function to create the React hooks and context provider for your app. Export `StructProvider`, `StructIdentityProvider` and `useStruct` from this file.

```TS
// lib/struct.ts

import { createStruct } from "@struct-app/react";

export const { StructProvider, useStruct, StructIdentityProvider } = createStruct();
```

You can optionally provide traits and event types as type parameters to `createStruct` to get type safety when using `useStruct` and `StructIdentityProvider`.

```TS
// lib/struct.ts

import type { event, traits } from "@struct-app/react";
import { createStruct } from "@struct-app/react";

type Events = {
  "purchase": event<{ value: number, currency: string, cartId: string }>;
  "login": event<{ method: "email" | "google" | "facebook" }>;
  "update profile": event<{ name: string, email: string }>;
}

type UserTraits = traits<{
  foo: string;
  type: "free" | "premium";
  age: number;
}>;

export const { StructProvider, useStruct, StructIdentityProvider } = createStruct<UserTraits, Events>();
```

### 2. Wrap your App with the `StructProvider`

```TSX
// App.tsx
import { StructProvider } from "./lib/struct"

function App() {
 return (
  <StructProvider apiKey="YOUR_API_KEY">
   {/* Your App */}
  </StructProvider>
 )
}
```

### 3. Setup Identity Tracking with `StructIdentityProvider`

To identify users and organisations, you can use the `StructIdentityProvider` component. This will automatically identify users and organisations when the component mounts and will update the user and organisation when the props change.

```TSX
// StructIdentityTracker.tsx
import { StructIdentityProvider } from "./lib/struct";

export default function StructIdentityTracker() {
 const { user } = useUser(); // Your user object from your auth provider

 return (
  <StructIdentityProvider
    userId={user.id ?? null}
    name={user.name}
    email={user.email}
    organisationId={user.organisationId}
    organisationName={user.organisationName}
    traits={{ foo: "bar", type: "premium", age: 30 }}
  />
 )
}
```

```JSX
// App.jsx
import { StructProvider } from "@struct-app/react";
import StructIdentityTracker from "./StructIdentityTracker";

function App() {
 return (
  <StructProvider apiKey="YOUR_API_KEY">
    <StructIdentityTracker />
    {/* Your App */}
  </StructProvider>
 )
}
```

> If for any reason you can't use the `StructIdentityProvider` component, you can use the `useStruct` hook to access the Struct client and call `identify` manually.

## Usage

### Track Events

The `useStruct` hook gives you access to the Struct client. You can use it to track events.

```JSX
// YourComponent.jsx

import { useStruct } from "./lib/struct";

function YourComponent() {
 const struct = useStruct();

 const onClick = () => {
  // Track custom events
  struct.track("login", { method: "email" });

  // Track conversion events with value
  struct.track("purchase", { value: 1000, currency: "USD" });
 }

 return (
  <button onClick={onClick}>
    Track Event
  </button>
 )
}
```

### Track Page Views (example with React Router)

Create a component that tracks page views when the location changes. This example uses React Router.

```JSX
// StructPageTracker.jsx
import { useStruct } from "./lib/struct";
import { useLocation } from "react-router-dom";

export default function StructPageTracker() {
 const struct = useStruct();
 const location = useLocation();

 useEffect(() => {
  struct.page();
 }, [location]);

 return null;
}
```

Now you can use the `StructPageTracker` component in your app to track page views automatically.

```JSX
// App.jsx
import { StructProvider } from "./lib/struct";
import StructPageTracker from "./StructPageTracker";

function App() {
 return (
  <StructProvider apiKey={'YOUR_API_KEY'}>
   <StructPageTracker />
   <YourApp />
  </StructProvider>
 )
}
```