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:

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.

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

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