You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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](MIGRATION.md).
9
+
This is the official JavaScript and TypeScript 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](MIGRATION.md).
10
10
11
11
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](https://www.optimizely.com/products/experiment/feature-experimentation/), or see the [developer documentation](https://docs.developers.optimizely.com/feature-experimentation/docs/introduction).
12
12
@@ -16,9 +16,8 @@ Optimizely Rollouts is [free feature flags](https://www.optimizely.com/free-feat
16
16
17
17
## Get Started
18
18
19
-
> For **Browser** applications, refer to the [JavaScript SDK's developer documentation](https://docs.developers.optimizely.com/feature-experimentation/docs/javascript-sdk) for detailed instructions on getting started with using the SDK within client-side applications.
19
+
> Refer to the [JavaScript SDK's developer documentation](https://docs.developers.optimizely.com/feature-experimentation/docs/javascript-sdk) for detailed instructions on getting started with using the SDK.
20
20
21
-
> For **Node.js** applications, refer to the [JavaScript (Node) variant of the developer documentation](https://docs.developers.optimizely.com/feature-experimentation/docs/javascript-node-sdk).
22
21
23
22
> For **Edge Functions**, we provide starter kits that utilize the Optimizely JavaScript SDK for the following platforms:
24
23
>
@@ -28,7 +27,7 @@ Optimizely Rollouts is [free feature flags](https://www.optimizely.com/free-feat
> 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.
30
+
> Note: We recommend using the **Lite**entrypoint (for version < 6) / **Universal** entrypoint (for version >=6) of the sdk for edge platforms. These starter kits also use the **Lite** variant of the JavaScript SDK.
32
31
33
32
### Prerequisites
34
33
@@ -73,7 +72,7 @@ import optimizely from 'npm:@optimizely/optimizely-sdk';
73
72
74
73
## Use the JavaScript SDK
75
74
76
-
See the [Optimizely Feature Experimentation developer documentation for JavaScript](https://docs.developers.optimizely.com/experimentation/v4.0.0-full-stack/docs/javascript-sdk) to learn how to set up your first JavaScript project and use the SDK for client-side applications.
75
+
See the [JavaScript SDK's developer documentation](https://docs.developers.optimizely.com/feature-experimentation/docs/javascript-sdk) to learn how to set up your first JavaScript project using the SDK.
77
76
78
77
The SDK uses a modular architecture with dedicated components for project configuration, event processing, and more. The examples below demonstrate the recommended initialization pattern.
79
78
@@ -121,15 +120,15 @@ optimizelyClient
121
120
});
122
121
```
123
122
124
-
### Initialization (Using HTML)
123
+
### Initialization (Using HTML script tag)
125
124
126
125
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](https://unpkg.com/):
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.
@@ -175,21 +174,49 @@ As `window.optimizelySdk` should be a global variable at this point, you can con
175
174
</script>
176
175
```
177
176
178
-
Regarding `EventDispatcher`s: In Node.js environment, the default `EventDispatcher` is powered by the [`http/s`](https://nodejs.org/api/http.html) module.
177
+
### Closing the SDK Instance
178
+
179
+
Depending on the sdk configuration, the client instance might schedule tasks in the background. If the instance has background tasks scheduled,
180
+
then the instance will not be garbage collected even though there are no more references to the instance in the code. (Basically, the background tasks will still hold references to the instance). Therefore, it's important to close it to properly clean up resources.
181
+
182
+
```javascript
183
+
// Close the Optimizely client when you're done using it
184
+
optimizelyClient.close()
185
+
```
186
+
Using the following settings will cause background tasks to be scheduled
187
+
188
+
- Polling Datafile Manager
189
+
- Batch Event Processor with batchSize > 1
190
+
- ODP manager with eventBatchSize > 1
191
+
192
+
193
+
194
+
> ⚠️ **Warning**: Failure to close SDK instances when they're no longer needed may result in memory leaks. This is particularly important for applications that create multiple instances over time. For some environment like SSR applications, it might not be convenient to close each instance, in which case, the `disposable` option of `createInstance` can be used to disable all background tasks on the server side, allowing the instance to be garbage collected.
195
+
196
+
197
+
## Special Notes
198
+
199
+
### Migration Guides
200
+
201
+
If you're updating your SDK version, please check the appropriate migration guide:
202
+
203
+
-**Migrating from 5.x or lower to 6.x**: See our [Migration Guide](MIGRATION.md) for detailed instructions on updating to the new modular architecture.
204
+
-**Migrating from 4.x or lower to 5.x**: Please refer to the [Changelog](CHANGELOG.md#500---january-19-2024) for details on these breaking changes.
179
205
180
206
## SDK Development
181
207
182
208
### Unit Tests
183
209
184
-
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.
210
+
There is a mix of testing paradigms used within the JavaScript SDK which include Mocha, Chai, Karma, and Vitest, indicated by their respective `*.tests.js` and `*.spec.ts` filenames.
185
211
186
212
When contributing code to the SDK, aim to keep the percentage of code test coverage at the current level ([](https://coveralls.io/github/optimizely/javascript-sdk)) or above.
187
213
188
-
To run unit tests on the primary JavaScript SDK package source code, you can take the following steps:
214
+
To run unit tests, you can take the following steps:
189
215
190
-
1. On your command line or terminal, navigate to the `~/javascript-sdk/packages/optimizely-sdk` directory.
191
-
2. Ensure that you have run `npm install` to install all project dependencies.
192
-
3. Run `npm test` to run all test files.
216
+
1. Ensure that you have run `npm install` to install all project dependencies.
217
+
2. Run `npm test` to run all test files.
218
+
3. Run `npm run test-vitest` to run only tests written using Vitest.
219
+
4. Run `npm run test-mocha` to run only tests written using Mocha.
193
220
4. (For cross-browser testing) Run `npm run test-xbrowser` to run tests in many browsers via BrowserStack.
194
221
5. Resolve any tests that fail before continuing with your contribution.
195
222
@@ -215,14 +242,6 @@ npm run test-xbrowser
215
242
216
243
For more information regarding contributing to the Optimizely JavaScript SDK, please read [Contributing](CONTRIBUTING.md).
217
244
218
-
## Special Notes
219
-
220
-
### Migration Guides
221
-
222
-
If you're updating your SDK version, please check the appropriate migration guide:
223
-
224
-
-**Migrating from 5.x to 6.x**: See our [Migration Guide](MIGRATION.md) for detailed instructions on updating to the new modular architecture.
225
-
-**Migrating from 4.x to 5.x**: Please refer to the [Changelog](CHANGELOG.md#500---january-19-2024) for details on these breaking changes.
226
245
227
246
### Feature Management access
228
247
@@ -232,7 +251,7 @@ To access the Feature Management configuration in the Optimizely dashboard, plea
232
251
233
252
`@optimizely/optimizely-sdk` is developed and maintained by [Optimizely](https://optimizely.com) and many [contributors](https://github.com/optimizely/javascript-sdk/graphs/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](https://www.optimizely.com/products/experiment/feature-experimentation/) to learn more.
234
253
235
-
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.
254
+
First-party code (under `lib/`) is copyright Optimizely, Inc., licensed under Apache 2.0.
0 commit comments