LaunchDarkly React Client SDK

Common errors

• Error: React hooks can only be called inside of the body of a function component. This could happen for one of the following reasons: 1. You might have mismatching versions of React and the renderer (such as React DOM) 2. You might be breaking the Rules of Hooks

  cause Attempting to use `useFlags` or `useLDClient` outside a functional React component or with an incompatible React version.
  fix Ensure `useFlags` and `useLDClient` are only called within functional React components. Verify `react` and `react-dom` versions are 16.8.0 or higher.

• LaunchDarkly: clientSideId must be specified.

  cause The `clientSideId` property was not provided or was an empty string during the initialization of `withLDProvider` or `asyncWithLDProvider`.
  fix Ensure `clientSideId` is correctly passed to `withLDProvider` or `asyncWithLDProvider`, typically loaded from environment variables (e.g., `process.env.REACT_APP_LD_CLIENT_SIDE_ID`).

• Cannot read properties of undefined (reading 'variation')

  cause Attempting to access a flag value from the `ldClient` or `useFlags` before the SDK has fully initialized or if the flag is not found/enabled for client-side SDKs.
  fix Ensure the SDK is fully initialized by checking `isInitialized` from the provider or by using the `waitForInitialization` option. Also, verify the flag exists and is enabled for client-side SDKs in the LaunchDarkly dashboard.

Warnings

• gotcha The React SDK requires a 'Client-side ID', not an 'SDK key' or 'Mobile key', for initialization. Using the wrong key will prevent the SDK from connecting.
  Fix: Always use the 'Client-side ID' found in your LaunchDarkly project settings. Ensure you are not exposing server-side SDK keys in client-side code.
• gotcha For any feature flag to be accessible in the client-side React SDK, the 'Make this flag available to client-side SDKs' checkbox must be enabled on the flag's settings page in the LaunchDarkly dashboard.
  Fix: Verify flag settings in the LaunchDarkly dashboard. If the flag is not client-side enabled, it will always return the default value provided in your code.
• breaking Using React Hooks (e.g., `useFlags`, `useLDClient`) or `asyncWithLDProvider` requires React version 16.8.0 or later. Earlier versions of React will result in runtime errors.
  Fix: Upgrade your project's `react` and `react-dom` packages to version 16.8.0 or higher. For older React versions, you must use the Higher-Order Component approach without hooks.
• breaking From `launchdarkly-react-client-sdk` v3.3.2 onwards, the build target for ESBuild was explicitly set to ES2015 to ensure broader browser compatibility, overriding potential `tsconfig.json` defaults.
  Fix: This change is a fix for compatibility. If you are on an older version and facing issues in older browsers with newer JS syntax, ensure your build process targets ES2015 or earlier, or upgrade to v3.3.2+.

Install

• npm install launchdarkly-react-client-sdk npm
• yarn add launchdarkly-react-client-sdk yarn
• pnpm add launchdarkly-react-client-sdk pnpm

Imports

• withLDProvider
  wrong:

  const { withLDProvider } = require('launchdarkly-react-client-sdk');

  correct:

  import { withLDProvider } from 'launchdarkly-react-client-sdk';

  This is the primary Higher-Order Component for initializing the SDK and making it available to your React app. ESM is preferred for modern React projects.
• useFlags

  import { useFlags } from 'launchdarkly-react-client-sdk';

  A React Hook to access all available flag values for the current user context. Requires React 16.8.0 or later.
• useLDClient

  import { useLDClient } from 'launchdarkly-react-client-sdk';

  A React Hook to get the underlying LaunchDarkly client instance for advanced operations like tracking events or identifying users. Requires React 16.8.0 or later.
• asyncWithLDProvider

  import { asyncWithLDProvider } from 'launchdarkly-react-client-sdk';

  Use this function for scenarios where you need to pre-initialize the LaunchDarkly client asynchronously before rendering your React application.

Quickstart

This quickstart initializes the LaunchDarkly SDK using `withLDProvider`, setting up an anonymous user and then demonstrating how to retrieve flag values within a functional component using the `useFlags` hook. It includes basic error handling for a missing client-side ID.

import React from 'react';
import { withLDProvider, useFlags } from 'launchdarkly-react-client-sdk';

const clientSideId = process.env.REACT_APP_LD_CLIENT_SIDE_ID ?? '';

if (!clientSideId) {
  console.error('LaunchDarkly Client-side ID is not set. Please set REACT_APP_LD_CLIENT_SIDE_ID in your environment variables.');
}

interface MyComponentProps {
  // any props for your component
}

const MyFeatureComponent: React.FC<MyComponentProps> = () => {
  const { myFeatureFlag, anotherFlag } = useFlags();

  return (
    <div>
      <h1>My Application</h1>
      {myFeatureFlag ? (
        <p>Feature is ON! Displaying content for the feature.</p>
      ) : (
        <p>Feature is OFF. Default content.</p>
      )}
      {anotherFlag && <p>Another flag is also ON!</p>}
    </div>
  );
};

const MyWrappedComponent = withLDProvider({
  clientSideId: clientSideId,
  user: { key: 'example-user', anonymous: true },
  options: { 
    evaluationReasons: true 
  }
})(MyFeatureComponent);

export default MyWrappedComponent;