@optimizely/optimizely-sdk

What is @optimizely/optimizely-sdk?

@optimizely/optimizely-sdk is a feature flagging and A/B testing library that allows developers to experiment with and optimize their applications. It provides tools for running experiments, managing feature flags, and personalizing user experiences.

What are @optimizely/optimizely-sdk's main functionalities?

Feature Flagging

This feature allows you to manage feature flags, enabling or disabling features for specific users or groups of users.

const optimizely = require('@optimizely/optimizely-sdk');
const optimizelyClient = optimizely.createInstance({
  sdkKey: 'your-sdk-key'
});

const userId = 'user123';
const featureEnabled = optimizelyClient.isFeatureEnabled('new_feature', userId);

if (featureEnabled) {
  console.log('Feature is enabled for this user');
} else {
  console.log('Feature is not enabled for this user');
}

A/B Testing

This feature allows you to run A/B tests by assigning users to different variations of an experiment and measuring their behavior.

const optimizely = require('@optimizely/optimizely-sdk');
const optimizelyClient = optimizely.createInstance({
  sdkKey: 'your-sdk-key'
});

const userId = 'user123';
const variation = optimizelyClient.activate('experiment_key', userId);

if (variation === 'variation_1') {
  console.log('User is in variation 1');
} else if (variation === 'variation_2') {
  console.log('User is in variation 2');
} else {
  console.log('User is in control group');
}

Event Tracking

This feature allows you to track events and user actions, which can be used to measure the impact of experiments and feature flags.

const optimizely = require('@optimizely/optimizely-sdk');
const optimizelyClient = optimizely.createInstance({
  sdkKey: 'your-sdk-key'
});

const userId = 'user123';
optimizelyClient.track('event_key', userId, { revenue: 100 });
console.log('Event tracked for user');

Other packages similar to @optimizely/optimizely-sdk

launchdarkly-node-server-sdk

LaunchDarkly is a feature management platform that provides similar functionality to Optimizely, including feature flagging, A/B testing, and user segmentation. It is known for its robust feature set and ease of use.

unleash-client

Unleash is an open-source feature management solution that offers feature toggling and gradual rollouts. It is a good alternative for those looking for a self-hosted solution with a strong community support.

splitio

Split.io is a feature experimentation platform that provides feature flagging, A/B testing, and real-time analytics. It is designed for teams looking to make data-driven decisions and optimize their applications.

README

Optimizely JavaScript SDK

This repository houses the JavaScript SDK for use with Optimizely Feature Experimentation and Optimizely Full Stack (legacy). The SDK now features a modular architecture for greater flexibility and control. If you're upgrading from a previous version, see our Migration Guide.

Optimizely Feature Experimentation is an A/B testing and feature management tool for product development teams that enables you to experiment at every step. Using Optimizely Feature Experimentation allows for every feature on your roadmap to be an opportunity to discover hidden insights. Learn more at Optimizely.com, or see the developer documentation.

Optimizely Rollouts is free feature flags for development teams. You can easily roll out and roll back features in any application without code deploys, mitigating risk for every feature on your roadmap.

Get Started

For Browser applications, refer to the JavaScript SDK's developer documentation for detailed instructions on getting started with using the SDK within client-side applications.

For Node.js applications, refer to the JavaScript (Node) variant of the developer documentation.

For Edge Functions, we provide starter kits that utilize the Optimizely JavaScript SDK for the following platforms:

• Akamai (Edgeworkers)
• AWS Lambda@Edge
• Cloudflare Worker
• Fastly Compute@Edge
• Vercel Edge Middleware

Note: We recommend using the Lite version of the sdk for edge platforms. These starter kits also use the Lite variant of the JavaScript SDK which excludes the datafile manager and event processor packages.

Prerequisites

Ensure the SDK supports all of the platforms you're targeting. In particular, the SDK targets modern ES6-compliant JavaScript environments. We officially support:

• Node.js >= 18.0.0. By extension, environments like AWS Lambda, Google Cloud Functions, and Auth0 Webtasks are supported as well. Older Node.js releases likely work too (try npm test to validate for yourself), but are not formally supported.
• Modern Web Browsers, such as Microsoft Edge 84+, Firefox 91+, Safari 13+, and Chrome 102+, Opera 76+

In addition, other environments are likely compatible but are not formally supported including:

• Progressive Web Apps, WebViews, and hybrid mobile apps like those built with React Native and Apache Cordova.
• Cloudflare Workers and Fly, both of which are powered by recent releases of V8.
• Anywhere else you can think of that might embed a JavaScript engine. The sky is the limit; experiment everywhere! 🚀

Install the SDK

Once you've validated that the SDK supports the platforms you're targeting, fetch the package from NPM:

Using npm:

npm install --save @optimizely/optimizely-sdk

Using yarn:

yarn add @optimizely/optimizely-sdk

Using pnpm:

pnpm add @optimizely/optimizely-sdk

Using deno (no installation required):

import optimizely from 'npm:@optimizely/optimizely-sdk';

Use the JavaScript SDK

See the Optimizely Feature Experimentation developer documentation for JavaScript to learn how to set up your first JavaScript project and use the SDK for client-side applications.

The SDK uses a modular architecture with dedicated components for project configuration, event processing, and more. The examples below demonstrate the recommended initialization pattern.

Initialization with Package Managers (npm, yarn, pnpm)

import {
  createInstance,
  createPollingProjectConfigManager,
  createBatchEventProcessor,
  createOdpManager,
} from '@optimizely/optimizely-sdk';

// 1. Configure your project config manager
const pollingConfigManager = createPollingProjectConfigManager({
  sdkKey: '<YOUR_SDK_KEY>',
  autoUpdate: true, // Optional: enable automatic updates
  updateInterval: 300000, // Optional: update every 5 minutes (in ms)
});

// 2. Create an event processor for analytics
const batchEventProcessor = createBatchEventProcessor({
  batchSize: 10, // Optional: default batch size
  flushInterval: 1000, // Optional: flush interval in ms
});

// 3. Set up ODP manager for segments and audience targeting
const odpManager = createOdpManager();

// 4. Initialize the Optimizely client with the components
const optimizelyClient = createInstance({
  projectConfigManager: pollingConfigManager,
  eventProcessor: batchEventProcessor,
  odpManager: odpManager,
});

optimizelyClient
  .onReady()
  .then(() => {
    console.log('Optimizely client is ready');
    // Your application code using Optimizely goes here
  })
  .catch(error => {
    console.error('Error initializing Optimizely client:', error);
  });

Initialization (Using HTML)

The package has different entry points for different environments. The browser entry point is an ES module, which can be used with an appropriate bundler like Webpack or Rollup. Additionally, for ease of use during initial evaluations you can include a standalone umd bundle of the SDK in your web page by fetching it from unpkg:

<script src="https://unpkg.com/@optimizely/optimizely-sdk/dist/optimizely.browser.umd.min.js"></script>

<!-- You can also use the unminified version if necessary -->
<script src="https://unpkg.com/@optimizely/optimizely-sdk/dist/optimizely.browser.umd.js"></script>

When evaluated, that bundle assigns the SDK's exports to window.optimizelySdk. If you wish to use the asset locally (for example, if unpkg is down), you can find it in your local copy of the package at dist/optimizely.browser.umd.min.js. We do not recommend using this method in production settings as it introduces a third-party performance dependency.

As window.optimizelySdk should be a global variable at this point, you can continue to use it like so:

<script>
  // Extract the factory functions from the global SDK
  const {
    createInstance,
    createPollingProjectConfigManager,
    createBatchEventProcessor,
    createOdpManager,
  } = window.optimizelySdk;

  // Initialize components
  const pollingConfigManager = createPollingProjectConfigManager({
    sdkKey: '<YOUR_SDK_KEY>',
    autoUpdate: true,
  });

  const batchEventProcessor = createBatchEventProcessor();

  const odpManager = createOdpManager();

  // Create the Optimizely client
  const optimizelyClient = createInstance({
    projectConfigManager: pollingConfigManager,
    eventProcessor: batchEventProcessor,
    odpManager: odpManager,
  });

  optimizelyClient
    .onReady()
    .then(() => {
      console.log('Optimizely client is ready');
      // Start using the client here
    })
    .catch(error => {
      console.error('Error initializing Optimizely client:', error);
    });
</script>

Regarding EventDispatchers: In Node.js environment, the default EventDispatcher is powered by the http/s module.

SDK Development

Unit Tests

There is a mix of testing paradigms used within the JavaScript SDK which include Mocha, Chai, Karma, and Jest, indicated by their respective *.tests.js and *.spec.ts filenames.

When contributing code to the SDK, aim to keep the percentage of code test coverage at the current level () or above.

To run unit tests on the primary JavaScript SDK package source code, you can take the following steps:

• On your command line or terminal, navigate to the ~/javascript-sdk/packages/optimizely-sdk directory.
• Ensure that you have run npm install to install all project dependencies.
• Run npm test to run all test files.
• (For cross-browser testing) Run npm run test-xbrowser to run tests in many browsers via BrowserStack.
• Resolve any tests that fail before continuing with your contribution.

This information is relevant only if you plan on contributing to the SDK itself.

# Prerequisite: Install dependencies.
npm install

# Run unit tests.
npm test

# Run unit tests in many browsers, currently via BrowserStack.
# For this to work, the following environment variables must be set:
#   - BROWSER_STACK_USERNAME
#   - BROWSER_STACK_PASSWORD
npm run test-xbrowser

/.github/workflows/javascript.yml contains the definitions for BROWSER_STACK_USERNAME and BROWSER_STACK_ACCESS_KEY used in the GitHub Actions CI pipeline. When developing locally, you must provide your own credentials in order to run npm run test-xbrowser. You can register for an account for free on the BrowserStack official website here.

Contributing

For more information regarding contributing to the Optimizely JavaScript SDK, please read Contributing.

Special Notes

Migration Guides

If you're updating your SDK version, please check the appropriate migration guide:

• Migrating from 5.x to 6.x: See our Migration Guide for detailed instructions on updating to the new modular architecture.
• Migrating from 4.x to 5.x: Please refer to the Changelog for details on these breaking changes.

Feature Management access

To access the Feature Management configuration in the Optimizely dashboard, please contact your Optimizely customer success manager.

Credits

@optimizely/optimizely-sdk is developed and maintained by Optimizely and many contributors. If you're interested in learning more about what Optimizely Feature Experimentation can do for your company you can visit the official Optimizely Feature Experimentation product page here to learn more.

First-party code (under packages/optimizely-sdk/lib/, packages/datafile-manager/lib, packages/datafile-manager/src, packages/datafile-manager/__test__, packages/event-processor/src, packages/event-processor/__tests__, packages/logging/src, packages/logging/__tests__, packages/utils/src, packages/utils/__tests__) is copyright Optimizely, Inc. and contributors, licensed under Apache 2.0.

Other Optimizely SDKs

• Agent - https://github.com/optimizely/agent

• Android - https://github.com/optimizely/android-sdk

• C# - https://github.com/optimizely/csharp-sdk

• Flutter - https://github.com/optimizely/optimizely-flutter-sdk

• Go - https://github.com/optimizely/go-sdk

• Java - https://github.com/optimizely/java-sdk

• PHP - https://github.com/optimizely/php-sdk

• Python - https://github.com/optimizely/python-sdk

• React - https://github.com/optimizely/react-sdk

• Ruby - https://github.com/optimizely/ruby-sdk

• Swift - https://github.com/optimizely/swift-sdk

Changelog

[6.0.0] - May 29, 2025

Breaking Changes

• Modularized SDK architecture: The monolithic createInstance call has been split into multiple factory functions for greater flexibility and control.
• Core functionalities (project configuration, event processing, ODP, VUID, logging, and error handling) are now configured through dedicated components created via factory functions, giving you greater flexibility and control in enabling/disabling certain components and allowing optimizing the bundle size for frontend projects.
• onReady Promise behavior changed: It now resolves only when the SDK is ready and rejects on initialization errors.
• event processing is disabled by default and must be explicitly enabled by passing a eventProcessor to the client.
• Event dispatcher interface updated to use Promises instead of callbacks.
• Logging is disabled by default and must be explicitly enabled using a logger created via a factory function.
• VUID tracking is disabled by default and must be explicitly enabled by passing a vuidManager to the client instance.
• ODP functionality is no longer enabled by default. You must explicitly pass an odpManager to enable it.
• Dropped support for older browser versions and Node.js versions earlier than 18.0.0.

New Features

• Added support for async user profile service and async decide methods (see dcoumentation for User Profile Service and Decide methods)

Migration Guide

For detailed migration instructions, refer to the Migration Guide.

Documentation

For more details, see the official documentation: JavaScript SDK.