--- title: Initialize the React Native SDK slug: feature-experimentation/docs/initialize-the-react-native-sdk docTags: createdAt: 2026-08-05T20:39:52.000Z --- Use the `createInstance` method to initialize the React Native SDK and instantiate a `Client` instance. Each client corresponds to the datafile representing the state of a project for a certain environment. ## Minimum SDK version v4.0.0+ For versions 3.x and earlier, see [React Native SDK prior to v4](docId\:LXmOS7VyTsw0iZDvX7GzL). ## Description The `createInstance` method accepts a modular configuration object. Unlike v3, where options like `sdkKey`, `datafile`, and event batching were top-level parameters, v4 uses dedicated factory functions for each component. :::BlockQuote **Important:** You must use `createInstance` from `@optimizely/react-sdk`, not from `@optimizely/optimizely-sdk`. A client created directly from the JS SDK will not work correctly with `` and hooks. ::: ## Parameters The following table lists the required and optional parameters for the `createInstance` configuration object: | Parameter | Type | Description | | ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `projectConfigManager` | `OpaqueConfigManager` | **Required.** Manages the datafile. Create with `createPollingProjectConfigManager` or `createStaticProjectConfigManager`. | | `eventProcessor` | `OpaqueEventProcessor` | Processes and dispatches events. Create with `createBatchEventProcessor` or `createForwardingEventProcessor`. **Opt-in** — if not provided, no events are dispatched. | | `logger` | `OpaqueLogger` | Logger instance. Create with `createLogger`. **Opt-in** — disabled by default. | | `errorNotifier` | `OpaqueErrorNotifier` | Error notification handler. Create with `createErrorNotifier`. | | `userProfileService` | `UserProfileService` | Synchronous user profile service for [sticky bucketing](docId\:eH-UMm_rOn_GdGDGLV6__). | | `userProfileServiceAsync` | `UserProfileServiceAsync` | Asynchronous user profile service for sticky bucketing. | | `defaultDecideOptions` | `OptimizelyDecideOption[]` | Default options applied to all decide calls. | | `odpManager` | `OpaqueOdpManager` | ODP manager for audience segments and events. Create with `createOdpManager`. **Opt-in** — if not provided, ODP is disabled. | | `vuidManager` | `OpaqueVuidManager` | Visitor UID manager. Create with `createVuidManager`. **Opt-in** — disabled by default. | ## Returns Instantiates a `Client` instance. In v4, `createInstance` throws an error on invalid config (v3 returned `null`). ## Example ### Instantiate with a datafile Use `createStaticProjectConfigManager` for a fixed datafile with no polling: ```javascript import { createInstance, createStaticProjectConfigManager, createForwardingEventProcessor, } from '@optimizely/react-sdk'; const optimizely = createInstance({ projectConfigManager: createStaticProjectConfigManager({ datafile: optimizelyDatafile, }), eventProcessor: createForwardingEventProcessor(), }); ``` ### Instantiate with the SDK key Use `createPollingProjectConfigManager` to have the SDK fetch and poll for the datafile: ```javascript import { createInstance, createPollingProjectConfigManager, createBatchEventProcessor, } from '@optimizely/react-sdk'; const optimizely = createInstance({ projectConfigManager: createPollingProjectConfigManager({ sdkKey: 'YOUR_SDK_KEY', }), eventProcessor: createBatchEventProcessor(), }); ``` ### Instantiate with both SDK key and datafile Use the given datafile immediately, then fetch and poll for updates in the background: ```javascript import { createInstance, createPollingProjectConfigManager, createBatchEventProcessor, } from '@optimizely/react-sdk'; const optimizely = createInstance({ projectConfigManager: createPollingProjectConfigManager({ sdkKey: 'YOUR_SDK_KEY', datafile: optimizelyDatafile, autoUpdate: true, }), eventProcessor: createBatchEventProcessor(), }); ``` ### Instantiate offline with SDK key The React Native SDK provides default datafile caching to support fast initialization and offline mode. This means you can initialize using the SDK key even when there is no Internet connectivity. Once downloaded, the datafile is stored in the cache on the user's device. When the SDK is initialized the next time, it uses the datafile from the cache if available and resolves the ready promise. It then continues to load the latest datafile from the server. This results in faster SDK initialization. ### Render an `OptimizelyProvider` with a client and user To use the React Native SDK hooks inside your app, render an `OptimizelyProvider` as the parent of your root app component. Provide your client as the `client` prop and a `user` object: ```javascript import { OptimizelyProvider, createInstance, createPollingProjectConfigManager, createBatchEventProcessor, } from '@optimizely/react-sdk'; const optimizely = createInstance({ projectConfigManager: createPollingProjectConfigManager({ sdkKey: 'YOUR_SDK_KEY', }), eventProcessor: createBatchEventProcessor(), }); export default function App() { return ( ' }} > ); } ``` ### Render an `OptimizelyProvider` in VUID-only mode For VUID-only mode (no user ID), pass an empty object as the `user` prop. The SDK uses an auto-generated visitor UID for decisions and event tracking. You must enable VUID by passing `createVuidManager` and `createOdpManager` to `createInstance`: ```javascript import { OptimizelyProvider, createInstance, createPollingProjectConfigManager, createBatchEventProcessor, createOdpManager, createVuidManager, } from '@optimizely/react-sdk'; const optimizely = createInstance({ projectConfigManager: createPollingProjectConfigManager({ sdkKey: 'YOUR_SDK_KEY', }), eventProcessor: createBatchEventProcessor(), odpManager: createOdpManager(), vuidManager: createVuidManager({ enableVuid: true, }), }); export default function App() { return ( ); } ``` ## Config manager factories | Factory | Use case | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | | `createPollingProjectConfigManager({ sdkKey, datafile?, autoUpdate?, updateInterval?, urlTemplate? })` | Fetches and polls for datafile updates. `sdkKey` is required. | | `createStaticProjectConfigManager({ datafile })` | Uses a fixed datafile with no polling. | ### Polling config manager options | Option | Type | Description | | ---------------- | ---------------- | ---------------------------------------------------------------------------- | | `sdkKey` | string | **Required.** The key associated with an environment in the project. | | `datafile` | string \| object | Optional initial datafile (JSON string or parsed object). | | `autoUpdate` | boolean | When `true`, automatic updates are enabled. Default: `true`. | | `updateInterval` | number | Update interval in milliseconds. Minimum: 1000. Default: 300000 (5 minutes). | | `urlTemplate` | string | Format string for the datafile URL. `%s` is replaced with the `sdkKey`. | ## Event processor factories | Factory | Use case | | ----------------------------------------------------------- | ---------------------------------- | | `createBatchEventProcessor({ batchSize?, flushInterval? })` | Batches events before dispatching. | | `createForwardingEventProcessor()` | Forwards each event immediately. | :::hint{type="info"} **Note** Event processing is **opt-in** in v4. If no `eventProcessor` is passed to `createInstance`, no events are dispatched. To disable event dispatching, simply omit the `eventProcessor` parameter. ::: ## Other configurable modules | Factory | Use case | | -------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `createOdpManager()` | Enables ODP integration (audience segments, events). | | `createVuidManager({ enableVuid })` | Enables visitor UID tracking. | | `createErrorNotifier({ handleError })` | Configures error notification. | | `createLogger({ logLevel })` | Creates a logger instance. See [Customize the React Native SDK logger](docId\:Tx8jKZGNq94e7nZDsSQhB). | ### Full client creation example ```javascript import { createInstance, createPollingProjectConfigManager, createBatchEventProcessor, createOdpManager, createVuidManager, createLogger, createErrorNotifier, DEBUG, } from '@optimizely/react-sdk'; const optimizely = createInstance({ projectConfigManager: createPollingProjectConfigManager({ sdkKey: 'YOUR_SDK_KEY', autoUpdate: true, updateInterval: 60000, }), eventProcessor: createBatchEventProcessor({ batchSize: 10, flushInterval: 2000, }), odpManager: createOdpManager(), vuidManager: createVuidManager({ enableVuid: true }), logger: createLogger({ logLevel: DEBUG }), errorNotifier: createErrorNotifier({ handleError: (error) => console.error('Custom error handler', error), }), }); ``` ## Dispose of the client For effective resource management, properly close the Optimizely client instance when it is no longer needed 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, especially in environments where resources are limited. See [Close Optimizely on application exit](docId\:wXTlKs_19O_Tmz8o5pGSt). ## Source files The language and platform source files containing the implementation for the React Native SDK are available on [GitHub](https://github.com/optimizely/react-sdk/blob/master/src/index.ts).