LaunchDarkly Server SDK for Shopify Oxygen Runtimes =========================== [![NPM][npm-badge]][npm-link] [![Actions Status][ci-badge]][ci-link] [![Documentation][ghp-badge]][ghp-link] [![NPM][npm-dm-badge]][npm-link] [![NPM][npm-dt-badge]][npm-link] # ⛔️⛔️⛔️⛔️ > [!CAUTION] > This SDK is in pre-release and not subject to backwards compatibility > guarantees. The API may change based on feedback. > > Pin to a specific minor version and review the [changelog](./CHANGELOG.md) before upgrading. # ☝️☝️☝️☝️☝️☝️ LaunchDarkly overview ------------------------- [LaunchDarkly](https://www.launchdarkly.com) is a feature management platform that serves trillions feature flags daily to help teams build better software, faster. [Get started](https://docs.launchdarkly.com/home/getting-started) using LaunchDarkly today! [![Twitter Follow](https://img.shields.io/twitter/follow/launchdarkly.svg?style=social&label=Follow&maxAge=2592000)](https://twitter.com/intent/follow?screen_name=launchdarkly) Supported Oxygen runtime versions ------------------------- This version of the LaunchDarkly SDK has been tested with Oxygen compatibility date `2025-01-01`. > Check [worker compatibility date](https://shopify.dev/docs/storefronts/headless/hydrogen/deployments/oxygen-runtime#worker-compatibility-flags) Getting started ----------- Install this package: ``` npm install @launchdarkly/shopify-oxygen-sdk --save ``` Import the module ``` import {init} from '@launchdarkly/shopify-oxygen-sdk'; ``` Declare required variables ``` const sdkKey = 'your-sdk-key'; const options = {}; const flagKey = 'your-flag'; const context = { kind: 'user', key: 'example-user-key', name: 'tester', }; const defaultValue = false; ``` Basic SDK usage example ``` const ldClient = await init(sdkKey, options); await ldClient.waitForInitialization({timeout: 10}); const flagValue = await ldClient.variation(flagKey, context, defaultValue); // Flush events and close the client before returning your response. await ldClient.flush(); ldClient.close(); ``` This SDK is designed to be created per request: call `init()` inside your request handler. Oxygen runs each request in its own execution context, and that execution context ends when your handler returns the response. The SDK therefore cannot use a periodic background flush to deliver analytics events, so how events are delivered is a decision you make in your handler: - **Do not call `flush()`.** Any events the SDK buffered during the request are discarded when the execution context ends. This is a legitimate choice, and it is functionally equivalent to setting `sendEvents: false`. The only difference is that the SDK still does the work of buffering events during the request. - **Call `flush()` before you return the response.** This is required for flag evaluation and identify events to reach LaunchDarkly: call `await ldClient.flush()` at the end of every request that evaluates a flag, as shown above. `close()` releases the client's timers but does not flush, so `close()` on its own does not deliver events. Options ----------- The SDK accepts an `options` object as its second argument to `init(sdkKey, options)`. The supported options for this SDK are shown below. ### cache `cache` defines how this SDK interacts with [Oxygen's native cache api](https://shopify.dev/docs/storefronts/headless/hydrogen/deployments/oxygen-runtime#cache-api). | Option | Type | Default | Description | | ------------ | ------- | -------------------- | ------------------------------------------- | | `ttlSeconds` | number | 30 | Time-to-live for cache entries, in seconds. | | `name` | string | 'launchdarkly-cache' | Name for the cache instance. | | `enabled` | boolean | true | Whether caching is enabled. | Example: ```js const options = { cache: { ttlSeconds: 60, // cache values for 60 seconds within the request name: 'my-custom-cache', enabled: true, }, }; ``` ### logger By default, the SDK uses an internal logger for diagnostic output. You may provide your own logger by specifying a compatible logger object under `logger`. | Option | Type | Default | Description | | ------ | ------ | ----------------------- | -------------------------------------- | | logger | object | a basic internal logger | Optional custom logger implementation. | Example: ```js const options = { logger: myCustomLogger, // must match the LD logger interface }; ``` --- See the source for default values and logic: - [validateOptions.ts](./src/utils/validateOptions.ts) - [createOptions.ts](./src/utils/createOptions.ts) Learn more ----------- Read our [documentation](https://docs.launchdarkly.com) for in-depth instructions on configuring and using LaunchDarkly. Testing ------- We run integration tests for all our SDKs using a centralized test harness. This approach gives us the ability to test for consistency across SDKs, as well as test networking behavior in a long-running application. These tests cover each method in the SDK, and verify that event sending, flag evaluation, stream reconnection, and other aspects of the SDK all behave correctly. Contributing ------------ We encourage pull requests and other contributions from the community. Check out our [contributing guidelines](../../../CONTRIBUTING.md) for instructions on how to contribute to this SDK. About LaunchDarkly ----------- - LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard. With LaunchDarkly, you can: - Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases. - Gradually roll out a feature to an increasing percentage of users, and track the effect that the feature has on key metrics (for instance, how likely is a user to complete a purchase if they have feature A versus feature B?). - Turn off a feature that you realize is causing performance problems in production, without needing to re-deploy, or even restart the application with a changed configuration file. - Grant access to certain features based on user attributes, like payment plan (eg: users on the ‘gold’ plan get access to more features than users in the ‘silver’ plan). Disable parts of your application to facilitate maintenance, without taking everything offline. - LaunchDarkly provides feature flag SDKs for a wide variety of languages and technologies. Read [our documentation](https://docs.launchdarkly.com/docs) for a complete list. - Explore LaunchDarkly - [launchdarkly.com](https://www.launchdarkly.com/ 'LaunchDarkly Main Website') for more information - [docs.launchdarkly.com](https://docs.launchdarkly.com/ 'LaunchDarkly Documentation') for our documentation and SDK reference guides - [apidocs.launchdarkly.com](https://apidocs.launchdarkly.com/ 'LaunchDarkly API Documentation') for our API documentation - [launchdarkly.com/blog](https://launchdarkly.com/blog/ 'LaunchDarkly Blog Documentation') for the latest product updates [npm-badge]: https://img.shields.io/npm/v/@launchdarkly/shopify-oxygen-sdk.svg?style=flat-square [npm-link]: https://www.npmjs.com/package/@launchdarkly/shopify-oxygen-sdk [npm-dm-badge]: https://img.shields.io/npm/dm/@launchdarkly/shopify-oxygen-sdk.svg?style=flat-square [npm-dt-badge]: https://img.shields.io/npm/dt/@launchdarkly/shopify-oxygen-sdk.svg?style=flat-square [ci-badge]: https://github.com/launchdarkly/js-core/actions/workflows/shopify-oxygen.yml/badge.svg [ci-link]: https://github.com/launchdarkly/js-core/actions/workflows/shopify-oxygen.yml [ghp-badge]: https://img.shields.io/static/v1?label=GitHub+Pages&message=API+reference&color=00add8 [ghp-link]: https://launchdarkly.github.io/js-core/packages/sdk/shopify-oxygen/docs/