Release 4.1.0

[4.1.0] - July 10, 2026

New Features

• Local Holdouts: Added support for Local Holdouts, enabling holdout experiments
  to be scoped to specific feature flag rules rather than applied globally.
  Local Holdouts let you measure the true incremental impact of individual features
  by holding out a subset of users from specific rollouts while still serving them other experiences.
  See Holdouts docs for more information.

Changed

• Don't send ODP identify event for single identifier

Bug Fixes

• Use attribute id instead of key for CMAB prediction requests
• Normalize decision event campaign_id, variation_id, and entity_id

Release 4.0.0

[4.0.0] - May 18, 2026

v4 is a ground-up rewrite of the React SDK. For a detailed upgrade guide, see MIGRATION.md. For the official documentation, see the React SDK Developer Docs.

New Features

• New hook API — useDecide, useDecideForKeys, useDecideAll replace the old useDecision, useExperiment, and useFeature hooks. Return type changed from positional tuples ([decision, clientReady, didTimeout]) to discriminated union objects ({ decision, isLoading, error }).
• Async decision hooks — useDecideAsync, useDecideForKeysAsync, useDecideAllAsync for use with CMAB (Contextual Multi-Armed Bandit) experiments and async User Profile Service lookups.
• useOptimizelyClient hook — Access the Optimizely Client instance directly (replaces withOptimizely HOC).
• useOptimizelyUserContext hook — Access the current OptimizelyUserContext, with { userContext, isLoading, error } return type. Use for event tracking and forced decisions.
• Modular client configuration — createInstance now accepts dedicated factory-created components (createPollingProjectConfigManager, createStaticProjectConfigManager, createBatchEventProcessor, createForwardingEventProcessor, createOdpManager, createVuidManager, createErrorNotifier, createLogger) for granular control and smaller bundles.
• CMAB support — Contextual Multi-Armed Bandit experiments via async decide hooks (useDecideAsync). New decide options: IGNORE_CMAB_CACHE, RESET_CMAB_CACHE, INVALIDATE_USER_CMAB_CACHE.
• Holdouts support — Holdouts Feature Experimentation capability.
• Feature Rollouts — A new experiment type combining Targeted Delivery simplicity with A/B test measurement capabilities, including full impact analytics and metric tracking.
• Async User Profile Service — Support for asynchronous user profile service lookups.
• getSendBeaconEventDispatcher export — New event dispatcher using the Beacon API for reliable event delivery on page unload.

Breaking Changes

• Underlying JS SDK upgraded from v5 to v6 — See the JavaScript SDK v6 Migration Guide for details.
• ESM only — No CommonJS entry point. Projects using require() must switch to ESM imports or configure their bundler.
• Node.js >=18.0.0 required (was >=14.0.0).
• Provider prop renamed — optimizely → client.
• Provider user prop no longer accepts a Promise — Resolve the user before rendering.
• Removed Provider props — isServerSide, userId, userAttributes.
• Default timeout changed — From 5000 ms to 30000 ms.
• onReady() behavior changed — Resolves on success, rejects on failure (no longer returns { success, reason }).
• createInstance throws on invalid config (previously returned null).
• Event processing, ODP, VUID, and logging are opt-in — Must be explicitly enabled via factory functions.
• Removed components — OptimizelyExperiment, OptimizelyFeature, OptimizelyVariation.
• Removed HOC — withOptimizely.
• Removed hooks — useDecision (renamed to useDecide), useExperiment, useFeature, useTrackEvent.
• Removed per-hook autoUpdate option — Hooks now automatically re-evaluate on datafile polling updates. No opt-in needed.
• Removed per-hook overrideUserId / overrideAttributes — Use separate <OptimizelyProvider> instances for different users instead.
• Removed exports — ReactSDKClient, OptimizelyContext, setLogger, setLogLevel, logOnlyEventDispatcher, enums, logging, errorHandler.
• createLogger replaces setLogger/setLogLevel — Logging disabled by default; pass createLogger({ logLevel }) to createInstance.
• getQualifiedSegments return type changed — Now returns { segments, error } instead of string[] | null.

Changed

• Null/undefined user behavior — Provider now accepts user={null} in addition to undefined. When no user is provided, hooks return { isLoading: true } instead of attempting to create a user context.

Release 3.4.0

[3.4.0] - Mar 9, 2026

New Features

• Add a server-safe bundle that is automatically resolved when imported in React Server Components, excluding client-only React APIs (#318)
• Add qualifiedSegments prop to OptimizelyProvider for passing pre-fetched ODP segments, enabling synchronous ODP-based decisions during SSR (#318)
• Add getQualifiedSegments utility for fetching ODP audience segments server-side (#318)

Enhancements

• Improve useExperiment, useFeature, and useDecision hooks to compute decisions when config and user context (including segments) are available, without waiting for onReady (#318)
• Add comprehensive server-side rendering integration guide covering SSR, SSG, and App Router patterns (#318)

Release 3.3.1

[3.3.1] - Dec 8, 2025

Changed

• Widen React Native peer dependency version ranges.
• Improve notification center type definitions with strongly-typed listener payloads.

Release 3.3.0

[3.3.0] - Oct 13, 2025

New Features

• Added customHeaders option to datafileOptions for passing custom HTTP headers in datafile requests.

Bug Fixes

• Fix the EventTags type to allow event properties.
• Fix typo in event.experimentIds field in project config.

Release 3.2.4

[3.2.4] - May 15, 2025

Bug fixes

• client.onReady() always returns false when ODP is off and user id is null bug fix.(#302)

Release 3.2.3

[3.2.3] - Nov 22, 2024

Bug fixes

• isClientReady logic adjustment.(#285)
• track method overrideAttribute bug fix.(#287)
• "OptimizelyProvider resets previously set user" bug fix.(#292)

Release 3.2.2

[3.2.2] - Aug 21, 2024

Bug fixes

• Multiple instances of the Logger make the log system unconfigurable - bug fix. (#276)

Release 3.2.1

[3.2.1] - Aug 15, 2024

Bug fixes

• clientReady is true even though internal client promise returns success == false bug fix(#273)
• useDecision hook set the update listener on overy render bug fix(#273)
• setForcedDecision does not reflect the changes in optmizely instance and useDecision hook bug fix(#274)

Changed

• Performance improvements in both hooks and client instance(#273, #274)

Release 3.2.0

[3.2.0] - July 10, 2024

New Features

• The new useTrackEvent hook is now available for tracking events within functional components. This hook offers all the existing track event functionalities provided by the SDK. (#268)