@jsontech/react

React hooks and provider for ShipIt feature flags.

Installation

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:

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:

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:

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:

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:

const [user, setUser] = useShipItUser();

Environment Variables

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

• SHIPIT_CLIENT_KEY - Client SDK key

// 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