Initialize the React SDK

21 min

Use the createInstance method to initialize the React SDK and instantiate an instance of the ReactSDKClient class. Each client corresponds to the datafile representing the state of a project for a certain environment.

Version

SDK v3.0.0 and higher

Description

The createInstance method accepts a configuration object to configure Optimizely.

Some parameters are optional because the React SDK provides a default implementation, but you can override these for your production environments. For example, you can override them to configure an error handlererror handler and loggerlogger to catch issues, an event dispatcherevent dispatcher to manage network calls, or a User Profile ServiceUser Profile Service to ensure sticky bucketingsticky bucketing.

Parameters

The following table lists the required and optional parameters in React (created by passing in a Config object. The Config class consists of these fields):

Parameter	Type	Description
`datafile` _optional_	string	The JSON string representing the project. An SDK key or datafile (or both) must be provided.
`sdkKey` _optional_	string	The key associated with an environment in the project. At least one `sdkKey` or datafile must be provided.
`eventDispatcher` _optional_	object	An event handler to manage network calls.
`logger` _optional_	object	A logger implementation to log issues.
`errorHandler` _optional_	object	An error handler object to handle errors.
`userProfileService` _optional_	object	A user profile service.
`datafileOptions` _optional_	object	Object with configuration for automatic datafile management. Can have `autoUpdate` (boolean), `urlTemplate` (string) and `updateInterval` (number) properties.
`defaultDecideOptions` _optional_	Array	Array of `OptimizelyDecideOption` enums. When the Optimizely client is constructed with this parameter, it sets the default decide options that are applied to all the `Decide` calls made during the lifetime of the Optimizely client. You can also pass options to individual `Decide` methods (does not override defaults).

Returns

Instantiates an instance of the Optimizely client class.

Example

In the React SDK, you can provide either sdkKey or datafile or both.

When initializing with just the datafile, the React SDK uses the given datafile.

When initializing with just the SDK key, the datafile is automatically downloaded.

When initializing with both the SDK key and datafile, the React SDK uses the given datafile to start, then downloads the latest version of the datafile in the background.

Instantiate with a datafile

First, get a copy of the datafile from Optimizely's server by including the following script in the <head> of your web application. This script adds the datafile on the global window variable window.optimizelyDatafile.

<script src="https://cdn.optimizely.com/datafiles/YOUR_SDK_KEY.json/tag.js"></script>

Once you have a datafile, you can instantiate an Optimizely client.

import { createInstance } from '@optimizely/react-sdk';

const optimizely = createInstance({
  datafile: window.optimizelyDatafile,
})

Instantiate with the SDK key

To instantiate using the SDK key, obtain the SDK key from your project's settings, then pass sdkKey as a string property in the options object you pass to the createInstance method.

import { createInstance } from '@optimizely/react-sdk';

const optimizely = createInstance({
  sdkKey: 'YOUR_SDK_KEY',
});

When you provide the sdkKey, the React SDK instance downloads the datafile associated with that sdkKey. When the download completes, the React SDK instance updates itself to use the downloaded datafile. This initialize method relies on continuous internet connectivity. In contrast, in the React Native SDKReact Native SDK, you can initialize with an SDK key even while your app is offline.

Render an OptimizelyProvider with a client and user

To use the React SDK components inside your app, render an OptimizelyProvider as the parent of your root app component. Provide your Optimizely instance as the optimizely prop and a user object.

import { OptimizelyProvider, createInstance  } from '@optimizely/react-sdk';

const optimizely = createInstance({
  datafile: window.datafile,
});

// using a function component
export default function App() {
 return (
   <OptimizelyProvider
     optimizely={optimizely}
     user={{id: '<YOUR_USER_ID>'}}>
     <App />
   </OptimizelyProvider>
 );
}

// or a class component
class App extends React.Component {
  render() {
    return (
      <OptimizelyProvider
      	optimizely={optimizely}
  			user={{id: 'YOUR_USER_ID'}}>
        <App />
      </OptimizelyProvider>
    );
  }
}

Notes

Customize datafile management behavior

To customize datafile management behavior, provide a datafileOptions object property inside the options object passed to createInstance. The following table lists the supported customizable options:

Option	Type	Description
autoUpdate	boolean	When true and sdkKey is provided in the createInstance options, automatic updates are enabled on this instance. The default value is false.
updateInterval	number	When automatic updates are enabled, this controls the update interval. The unit is milliseconds. The minimum allowed value is 1000 (1 second). The default value is 300000 milliseconds (5 minutes).
urlTemplate	string	A format string used to build the URL from which the React SDK requests datafiles. Instances of %s are replaced with the sdkKey. When not provided, the React SDK requests datafiles from the Optimizely CDN.
customHeaders	object (Record<string>,<string>)	Lets you pass custom HTTP headers while fetching the datafile. Available in React SDK versions >= 3.3.0.

The following example shows how to customize datafile management behavior:

import { createInstance } from '@optimizely/react-sdk';

const optimizely = createInstance({
  sdkKey: 'YOUR_SDK_KEY',
  datafileOptions: {
    autoUpdate: true,
    updateInterval: 600_000, // 10 minutes in milliseconds
    urlTemplate: 'http://localhost:5000/datafiles/%s.json',
  },
});

Considerations with development mode

If you have created your React application using Create React App or are using a different type of development environment that uses hot reloading, there is a possibility of experiencing unusual behavior.

When running your application in development mode with hot reloading, for example, when using npm start, you may see that the React SDK is initialized more than once. This may cause inconsistent behavior, such as the page re-rendering multiple times or users being bucketed into incorrect variations.

This is not a problem with the React SDK. Instead, this happens when you wrap your application in React.StrictMode, which purposely renders the application twice in development mode to detect potential issues. To avoid this, disable the strict mode for the top-level component and move it to the lower-level components.

When building your app for production usenpm run build and host it on a web server. Doing so ensures the React SDK is not initialized more than once.

Dispose of the client

For effective resource management with the React SDK, you must properly close the Optimizely client instance when it is no longer needed. This is done by calling optimizely.close().

The .close() method ensures that the processes and queues associated with the instance are properly released. This is essential for preventing memory leaks and ensuring that the application runs efficiently, especially in environments where resources are limited or in applications that create and dispose of many instances over their lifecycle.

See Close Optimizely on application exit.

OdpManager

The OdpManager contains all the logic supporting Real-Time Audiences for Feature Experimentation-related features, including audience segments. You must configure this parameter to use Real-Time Audiences for Feature Experimentation.

The React SDK enables the Real-Time Audiences for Feature Experimentation methods by default. But, the methods do nothing unless you have enabled and configured Real-Time Audiences for Feature ExperimentationReal-Time Audiences for Feature Experimentation.

Note If necessary, to disable Real-Time Audiences for Feature Experimentation altogether, set disabled: true in the odpOptions. See the following sample code for information.

The following settings are optionally configurable when the React SDK is initialized:

ODP SegmentsCache size – segmentsCacheSize

Default – 100

Set to 0 to disable caching.

ODP SegmentsCache timeout (in seconds) – segmentsCacheTimeout

Default – 600 secs (10 minutes)

Set to 0 to disable timeout (never expires).

ODP enable – disabled

Default – false (enabled)

When disabled, the React SDK will disable ODP-related features. The React SDK still creates and manages VUID regardless of this flag and supports VUID-based decisions. See anonymous usersanonymous users.

The React SDK returns or logs an odpNotEnabled error when ODP is disabled and its features are requested.

OdpSegmentManager

This module provides an interface to the remote ODP server for audience segment mappings.

It fetches all qualified segments for the given user context and returns them as a string array in the completion handler.

It also manages a segment's cache shared for all user contexts. The cache is in memory (not persistent), and rebooting the device or terminating the app resets it.

OdpEventManager

This module provides an interface to the remote ODP server for events.

It queues all pending events (persistent) and sends them (in batches of up to 10) to the ODP server when all resources are available, including network connection and ODP public key (in the SDK's datafile).

Note The React SDK tries to dispatch all events (stored in a persistent queue and retried on recoverable errors) but does not guarantee completion.

The React SDK does not have direct access to OdpManager, OdpSegmentManager, nor OdpEventManager. These are managed by the underlying Javascript SDK. There are configuration options that can be set during the Optimizely client instantiation.

// You must configure Real-Time Audiences for Feature Experimentation

import { createInstance } from '@optimizely/react-sdk';

const optimizely = createInstance({
  sdkKey: 'YOUR_SDK_KEY',
  //...other Config options
  // The most common Real-Time Audiences for Feature Experimentation control is to explicitly disable the feature 
  odpOptions: {
  	disabled: true,
  },
  // Other options are as defined by OdpOptions in the Javascript SDK
  // https://github.com/optimizely/javascript-sdk/blob/master/lib/shared_types.ts
});

Server-side rendering

The React SDK supports server-side rendering (SSR). Pre-fetch the datafile and pass it to createInstance so decisions are available synchronously. Server-side instances are short-lived (created per request), so configure them to avoid unnecessary background work.

import { createInstance, OptimizelyProvider, OptimizelyDecideOption, useDecision } from '@optimizely/react-sdk';

function App() {
  const isServerSide = typeof window === 'undefined';
  const [optimizely] = useState(() =>
    createInstance({
      datafile,
      sdkKey: process.env.NEXT_PUBLIC_OPTIMIZELY_SDK_KEY || '',
      datafileOptions: { autoUpdate: !isServerSide },
      defaultDecideOptions: isServerSide ? [OptimizelyDecideOption.DISABLE_DECISION_EVENT] : [],
      odpOptions: {
        disabled: isServerSide,
      },
    })
  );
}

function MyComponent() {
  const [decision] = useDecision('flag1');
  return decision.enabled ? <p>Feature enabled</p> : <p>Feature disabled</p>;
}

<OptimizelyProvider optimizely={optimizelyClient} user={{ id: 'user1' }} isServerSide={isServerSide}>
  <MyComponent />
</OptimizelyProvider>;

Configure the instance for server use

Option	Server value	Why
datafile	Pre-fetched datafile JSON	Provides the datafile directly so the SDK is ready synchronously to make decisions.
datafileOptions.autoUpdate	false	No need to poll for datafile updates on a per-request instance.
defaultDecideOptions	[DISABLE_DECISION_EVENT]	Avoids duplicate decision events if the client will also fire them after hydration.
odpOptions.disabled	true	Disables ODP event manager processing during SSR. Avoids unnecessary event batching, API calls, and VUID tracking overhead.

Note Disabling ODP audience segments during SSR prevents automatic segment fetching, but you can still make audience-segment-based decisions by passing pre-fetched segments using the qualifiedSegments prop on OptimizelyProvider.

getQualifiedSegments

A standalone async utility that fetches qualified ODP audience segments for a user, given a datafile. It parses the datafile to extract ODP configuration and segment conditions, queries the ODP GraphQL API, and returns only the segments where the user is qualified.

import { getQualifiedSegments } from '@optimizely/react-sdk';

const segments = await getQualifiedSegments(userId, datafile);

Argument	Type	Description
userId	string	The user ID to fetch qualified segments for.
datafile	string \| Record<string, any>	The Optimizely datafile (JSON object or string).

Returns Promise<string[] | null>

Note The ODP segment fetch adds latency to server rendering. Consider caching the result per user to avoid re-fetching on every request.

React Server Components

Since version 3.4.0, the React SDK can be used directly in React Server Components without OptimizelyProvider. Create an instance, set the user, wait for readiness, and make decisions, all within an async server component.

import { createInstance } from '@optimizely/react-sdk';

export default async function ServerExperiment() {
  const client = createInstance({
    sdkKey: process.env.OPTIMIZELY_SDK_KEY || '',
  });

  client.setUser({
    id: 'user-123',
  });

  await client.onReady();

  const decision = client.decide('flag-1');

  client.close();

  return decision.enabled ? <h1>Experiment Variation</h1> : <h1>Control</h1>;
}

SSR limitations

Datafile required – SSR requires a pre-fetched datafile. Using sdkKey alone falls back to a failed decision.

User Promise not supported – SSR does not support user Promise.

ODP segments – ODP audience segments require async I/O and are not available during server rendering. Use getQualifiedSegments to pre-fetch segments server-side and pass them with the qualifiedSegments prop on OptimizelyProvider to enable synchronous ODP-based decisions. Without it, consider deferring the decision to the client using the fallback pattern.

For framework-specific SSR patterns, see the Next.js Integration GuideNext.js Integration Guide.

Source files

The language and platform source files containing the implementation for React SDK are available on GitHub.