Skip to main content

React SDK Getting Started

Npm package version GitHub

There are two ways to initialize the SDK:

  • Non-Blocking: This loads your application and makes a request to initialize the SDK in the background. Once this request is complete, your application will be ready to use the SDK.
  • Blocking: This allows you to delay the rendering of your application until the request to initialize the SDK is completed.

To use the provider, you must get the SDK Key from the DevCycle Dashboard. You can optionally pass in a user object to the provider to initialize the SDK. If you do not pass in a user to the provider, it will create an anonymous user and initialize the SDK with it. You can then call the identifyUser method on the client once the user has been authenticated. See Identifying Users & Setting Properties for more details.


It’s best to initialize DevCycle in your root component (App.jsx or App.tsx), so that its hooks can be accessed from anywhere within your application.


The withDevCycleProvider higher-order component (HOC) initializes the React SDK and wraps your root component. This provider may cause your app to flicker when it is first rendered, as all DevCycle variables will return their default values until the SDK is initialized.

import { withDevCycleProvider } from '@devcycle/react-client-sdk'
function App() {
return <TheRestofYourApp/>
export default withDevCycleProvider({ sdkKey: '<DEVCYCLE_CLIENT_SDK_KEY>' })(App)


The useIsDevCycleInitialized hook allows you to block rendering of your application until SDK initialization is complete. This ensures your app does not flicker due to value changes and enables you to control what you want displayed when initialization isn't finished yet.

import { useIsDevCycleInitialized, withDevCycleProvider } from '@devcycle/react-client-sdk'

function App() {
const dvcReady = useIsDevCycleInitialized()

if (!dvcReady) return <LoadingState/>
return <TheRestofYourApp/>

export default withDevCycleProvider({ sdkKey: '<DEVCYCLE_CLIENT_SDK_KEY>' })(App)

Deferred Initialization​

In many cases, user data is not available at the time the DevCycleProvider is created. If the provider is not passed a user object, then by default the SDK will be instantiated with an "anonymous" user and a configuration will be downloaded from DevCycle. The SDK will be considered "initialized" and the aforementioned useIsDevCycleInitialized hook will return true once this configuration has been downloaded.

If you would like to defer initialization of the SDK until your user data is available, you can pass the deferInitialization option to the DevCycleProvider. This will cause the SDK to not fetch a configuration until the devcycleClient.identifyUser method is called with the user data. The useIsDevCycleInitialized hook will return false until that method has been called and a corresponding config has been retrieved. Until that config is retrieved, all calls to retrieve variable values will return their default values.

import { useIsDevCycleInitialized, withDevCycleProvider } from '@devcycle/react-client-sdk'

let identified = false
function App() {
// e.g. a React Query style hook that retrieves user data
const { data: user, isFetched } = useUserFromMyUserStorage()
if (user && !identified) {
identified = true
const dvcReady = useIsDevCycleInitialized()

// rendering is blocked until the user is loaded, and has finished being identified in DevCycle
if (!dvcReady) return <LoadingState/>
return <TheRestofYourApp/>

export default withDevCycleProvider({
options: {
deferInitialization: true

Provider Config​

The withDevCycleProvider function accepts a Provider Config object:

DevCycle ProviderConfig Typescript Schema

sdkKeyStringSDK key
userDevCycleUserDevCycleUser object
optionsDevCycleOptionsDevCycleOptions object

Initialization Options​

The SDK exposes various initialization options which can be set by passing a DevCycleOptions object in the Provider Config:

DevCycleOptions Typescript Schema

DevCycle OptionTypeDescription
enableEdgeDBBooleanEnables the usage of EdgeDB for DevCycle that syncs User Data to DevCycle.
loggerDevCycleLoggerLogger override to replace default logger
logLevelDevCycleDefaultLogLevelSet log level of the default logger. Options are: debug, info, warn, error. Defaults to info.
eventFlushIntervalMSNumberControls the interval between flushing events to the DevCycle servers in milliseconds, defaults to 10 seconds.
flushEventQueueSizeNumberControls the maximum size the event queue can grow to until a flush is forced. Defaults to 100.
maxEventQueueSizeNumberControls the maximum size the event queue can grow to until events are dropped. Defaults to 1000.
apiProxyURLStringAllows the SDK to communicate with a proxy of DevCycle bucketing API / client SDK API.
configCacheTTLNumberThe maximum allowed age of a cached config in milliseconds, defaults to 7 days
disableConfigCacheBooleanDisable the use of cached configs
disableRealtimeUpdatesBooleanDisable Realtime Updates
deferInitializationBooleanDefer initialization (fetching configuration from DevCycle) until user is identified with identifyUser call
disableAutomaticEventLoggingBooleanDisables logging of sdk generated events (e.g. variableEvaluated, variableDefaulted) to DevCycle.
disableCustomEventLoggingBooleanDisables logging of custom events, from track() method, and user data to DevCycle.