npm package: @jsontech/react
Description: React hooks and provider for ShipIt feature flags.
Latest version: 0.0.69

# @jsontech/react

React hooks and provider for ShipIt feature flags.

## Installation

```bash
npm install @jsontech/react
# or
pnpm add @jsontech/react
# or
yarn add @jsontech/react
```

**Peer Dependencies:**

- `react >= 18`
- `react-dom >= 18`

## Usage

### Setup Provider

Wrap your app with `ShipItProvider`:

```typescript
import { ShipItProvider } from '@jsontech/react';

export function App() {
  return (
    <ShipItProvider
      config={{
        // SDK automatically uses window.location.origin in browser
        sdkKey: 'your-client-key-here' // Client key for browser
      }}
      initialUser={{ id: 'user-123' }}
    >
      {/* Your app */}
    </ShipItProvider>
  );
}
```

### Read Flags

Use the `useBoolFlag` hook to read boolean flags:

```typescript
import { useBoolFlag } from '@jsontech/react';

export function NewNav() {
  const { value, loading, error } = useBoolFlag('new-nav', false);
  
  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return value ? <div>New nav ON</div> : <div>New nav OFF</div>;
}
```

### Update User

Use the `useShipItUser` hook to get and update the current user:

```typescript
import { useShipItUser } from '@jsontech/react';

export function UserSwitcher() {
  const [user, setUser] = useShipItUser();

  return (
    <button
      onClick={() =>
        setUser({
          ...(user ?? { id: 'user-123' }),
          meta: { ...(user?.meta ?? {}), companyId: 'northwind' }
        })
      }
    >
      Switch user
    </button>
  );
}
```

## API Reference

### `ShipItProvider`

Provider component that wraps your app and provides the ShipIt client context.

#### Props

- `config: ShipItReactConfig` - Configuration object
  - `sdkKey?: string` - Client SDK key (recommended). If not provided, reads from `SHIPIT_CLIENT_KEY` env var.
  - `projectKey?: string` - Legacy: project key (requires `envKey`). Not recommended.
  - `envKey?: string` - Environment key (default: `'production'`). Only used with `projectKey`.
- `initialUser: ShipItUserPayload` - Initial user payload
- `user?: ShipItUserPayload` - Controlled user (requires `onUserChange`)
- `onUserChange?: (user: ShipItUserPayload) => void` - Callback for user changes (required if using controlled `user`)
- `children: React.ReactNode` - Your app components

### `useBoolFlag(flagKey: string, defaultValue: boolean)`

Hook to evaluate a boolean feature flag.

**Returns:**

- `value: boolean` - The flag value
- `loading: boolean` - Whether the evaluation is in progress
- `error: Error | null` - Error if evaluation failed

**Example:**

```typescript
const { value, loading, error } = useBoolFlag('feature-flag', false);
```

### `useShipItUser()`

Hook to get and update the current user.

**Returns:**

`[user: ShipItUserPayload | null, setUser: (user: ShipItUserPayload) => void]`

**Example:**

```typescript
const [user, setUser] = useShipItUser();
```

## Environment Variables

The SDK automatically reads from environment variables if `sdkKey` is not provided:

- `SHIPIT_CLIENT_KEY` - Client SDK key

```typescript
// This will use SHIPIT_CLIENT_KEY from env if sdkKey is not provided
<ShipItProvider config={{}} initialUser={{ id: 'user-123' }}>
  {/* ... */}
</ShipItProvider>
```

## API Base URL

The SDK automatically uses `window.location.origin` in the browser (assumes API is on same origin). The API URL cannot be overridden.

## SDK Keys

Use **client keys** for browser/mobile applications. Client keys are not secret and will be visible in your JavaScript bundle.

Get your SDK keys from your ShipIt Console → Environments.

## License

MIT