@toggle.tiger/toggletiger/README.md

A package to retrieve configuration from blobstore based on org, app, env, and config ID.

# ToggleTiger React SDK

The ToggleTiger React SDK provides a React component and hook to easily integrate feature flags from the ToggleTiger service into your React application. It supports fetching, caching, real-time updates via polling, and type coercion for flag values.

## Installation

To install the package, run:

```bash
npm install toggletiger
# or
yarn add toggletiger
```

## Usage

Wrap your application (or a part of it) with the `FeatureFlagProvider` and use the `useFeatureFlag` hook to access your feature flags.

```tsx
// App.tsx
import React from 'react';
import FeatureFlagProvider from 'toggletiger'; // Default import
import MyComponent from './MyComponent';

function App() {
  return (
    <FeatureFlagProvider
      sdkKey="YOUR_SDK_KEY"
      baseUrl="OPTIONAL_BASE_URL_IF_SELF_HOSTING"
      pollingInterval={30000} // Optional: Poll for updates every 30 seconds
    >
      <MyComponent />
    </FeatureFlagProvider>
  );
}

export default App;
```

```tsx
// MyComponent.tsx
import React from 'react';
import { useFeatureFlag } from 'toggletiger'; // Named import

function MyComponent() {
  const showNewFeature = useFeatureFlag('newFeatureToggle', false); // Default value is false
  const maxItems = useFeatureFlag('maxItemsCount', 10); // Default value is 10
  const welcomeMessage = useFeatureFlag('welcomeMessage', 'Hello Guest!'); // Default value

  if (showNewFeature) {
    return (
      <div>
        <h1>Welcome to the new feature!</h1>
        <p>{welcomeMessage}</p>
        <p>You can see up to {maxItems} items.</p>
      </div>
    );
  }

  return <div>Old feature content. Welcome message: {welcomeMessage}</div>;
}

export default MyComponent;
```

## `FeatureFlagProvider` Props

-   `sdkKey: string` (required): Your unique SDK key from the ToggleTiger dashboard.
-   `baseUrl?: string` (optional): The base URL for the ToggleTiger API. Defaults to the ToggleTiger cloud service. Use this if you are self-hosting.
-   `pollingInterval?: number` (optional): The interval in milliseconds at which the SDK will poll for configuration updates. If not provided or set to 0, polling is disabled. Recommended value: 30000 (30 seconds) or higher.
-   `children: ReactNode` (required): Your application components.

## `useFeatureFlag` Hook

`useFeatureFlag(key: string, defaultValue: any): any`

-   `key: string` (required): The key of the feature flag as defined in the ToggleTiger dashboard.
-   `defaultValue: any` (required): The default value to return if the flag is not found, the SDK is still loading, or an error occurs. The type of the default value is important for type inference if you are using TypeScript.

### Type Coercion

The `useFeatureFlag` hook automatically coerces the flag value (which is a string from the API) to the type specified in your ToggleTiger flag configuration (`boolean`, `number`, `string`).

-   **Boolean**: `"true"` becomes `true`, `"false"` becomes `false`. Invalid boolean strings will result in the `defaultValue`.
-   **Number**: Numeric strings like `"123"` or `"45.67"` are converted to numbers. Invalid numeric strings will result in the `defaultValue`.
-   **String**: String values are returned as is.

If a flag's type is not one of `boolean`, `number`, or `string`, or if the value cannot be coerced, the `defaultValue` will be returned.

## Caching

The SDK caches the latest known configuration in `localStorage` to provide flag values immediately on application load and to serve as a fallback if the API is temporarily unavailable. It uses ETag and Last-Modified headers to efficiently fetch updates.

## License

This project is licensed under the MIT License.