# React SDK (/docs/sdk/react)

The React SDK sits around the [Javascript Client SDK](/docs/sdk/javascript#client) and gives React specific handlers.

## Install [#install]

```bash
npm i @obelism/improve-sdk-react
```

## Setup [#setup]

In your config folder create the following file: `improveClient.ts`

```ts
import { generateImproveProvider } from '@obelism/improve-sdk-react'

export default generateImproveProvider(...)
```

## API [#api]

### generateImproveProvider [#generateimproveprovider]

```ts
generateImproveProvider(improveArgs: ImproveSetupArgs) => ({
    ImproveProvider,
    useImproveStatus,
    usePostAnalytic,
    useTestValue,
    useFlagValue
})
```

Setup function that generates the React component and hooks. The argument is the same [`ImproveSetupArgs`](/docs/sdk/javascript#types) used by the Client SDK (`organizationId`, `environment`, optional `config`, `fetchTimeout`, `baseUrl`, `dataLayer`, …).

### ImproveProvider [#improveprovider]

```ts
<ImproveProvider>
    {children}
</ImproveProvider>
```

On mount this automatically fetches the ImproveSDK and the config if not provided initially. Exposes a context that is used to populate data to the hooks down the component tree.

### useImproveStatus [#useimprovestatus]

```ts
const status: 'loading' | 'setup' | 'error' = useImproveStatus()
```

Reports where the provider is in its lifecycle: `loading` while the SDK and config are being fetched, `setup` once it's ready, or `error` if setup failed. Useful for rendering a fallback until the SDK is ready.

### useFlagValue [#useflagvalue]

```ts
const value: string = useFlagValue(flagSlug: string, fallback?: string)
```

Wrapper around [getFlagValue](/docs/sdk/javascript#getflagvalue) that's passed down when the context is set up. Returns `fallback` (when provided) while the config is still loading or when no flag matches the slug.

### useTestValue [#usetestvalue]

```ts
const value: string = useTestValue(testSlug: string, fallback?: string)
```

Wrapper around [getTestValue](/docs/sdk/javascript#gettestvalue) that's passed down when the context is set up. Returns `fallback` (when provided) while the config is still loading or when no test matches the slug.

### usePostAnalytic [#usepostanalytic]

`usePostAnalytic` takes no arguments and returns a global `postAnalytic` function. Events are **test-independent**: call the returned function with an event name, a required `scope` (a short, stable identifier for where/what the event refers to, not display text), and an optional payload, and the server attributes the event to whichever tests/flags the visitor was exposed to. Exposure is recorded by reading a variant with [useTestValue](/docs/sdk/react#usetestvalue) / [useFlagValue](/docs/sdk/react#useflagvalue).

```ts
const postAnalytic = usePostAnalytic()

// Simple event
<button onClick={() => postAnalytic('add_to_cart', 'product_page')} />

// With a value for revenue / AOV, and GA4 ecommerce params for GTM
<button
	onClick={() =>
		postAnalytic('purchase', 'checkout', {
			value: 72.05,
			currency: 'USD',
			params: { ecommerce: { transaction_id: 'T_1', items: [/* … */] } },
		})
	}
/>
```

Wrapper around [postAnalytic](/docs/sdk/javascript#postanalytic) that's passed down when the context is set up.

## NextJS App router [#nextjs-app-router]

For NextJS we need to make sure the generated provider is marked as a client component. For this we need to declare the `ImproveProvider` within the file where we declare `"use client"`.

This is needed because the ImproveProvider uses a `useEffect` to asynchronously fetch/load the JS SDK and fetch the config if needed. After it's set up it uses context to pass the data down.

```ts
'use client'

import { generateImproveProvider } from 'utils/generateImproveProvider'

const improveReact = generateImproveProvider(...)

export const ImproveProvider = improveReact.ImproveProvider
export const useTestValue = improveReact.useTestValue
export const useFlagValue = improveReact.useFlagValue
export const usePostAnalytic = improveReact.usePostAnalytic
```
