Skip to content

Commit 1b1ece4

Browse files
annabfenskejoepeeplesStefonSimmons
authored
add react & js docs for feature flag setup (#33281)
* add react & js docs for feature flag setup * add menu items for javascript & react * revert empty-space changes nothing wrong with these, but they are distracting in the diff * alphabetically reorder client SDKs in tiles partial * fix links (further reading) * Apply suggestions from code review correct alt text in JavaScript tile in partial Co-authored-by: StefonSimmons <57869435+StefonSimmons@users.noreply.github.com> * Update content/en/feature_flags/client/javascript.md Co-authored-by: Joe Peeples <joe.peeples@datadoghq.com> * Update content/en/feature_flags/client/javascript.md Co-authored-by: Joe Peeples <joe.peeples@datadoghq.com> * Update content/en/feature_flags/client/react.md Co-authored-by: Joe Peeples <joe.peeples@datadoghq.com> * add suspense to docs, add missing await, reorder client-side docs to show js/react first * fix typo in suspense section --------- Co-authored-by: Joe Peeples <joe.peeples@datadoghq.com> Co-authored-by: StefonSimmons <57869435+StefonSimmons@users.noreply.github.com>
1 parent 8528d1b commit 1b1ece4

File tree

9 files changed

+9211
-1
lines changed

9 files changed

+9211
-1
lines changed

‎config/_default/menus/main.en.yaml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5727,6 +5727,16 @@ menu:
57275727
parent: feature_flags_client
57285728
identifier: feature_flags_client_ios
57295729
weight: 102
5730+
- name: JavaScript
5731+
url: feature_flags/client/javascript
5732+
parent: feature_flags_client
5733+
identifier: feature_flags_client_javascript
5734+
weight: 103
5735+
- name: React
5736+
url: feature_flags/client/react
5737+
parent: feature_flags_client
5738+
identifier: feature_flags_client_react
5739+
weight: 104
57305740
- name: Server SDKs
57315741
url: feature_flags/server
57325742
parent: feature_flags

‎content/en/feature_flags/client/javascript.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
---
2+
title: JavaScript Feature Flags
3+
description: Set up Datadog Feature Flags for browser JavaScript applications.
4+
further_reading:
5+
- link: "/feature_flags/client/"
6+
tag: "Documentation"
7+
text: "Client-Side Feature Flags"
8+
- link: "https://openfeature.dev/docs/reference/sdks/client/web/"
9+
tag: "OpenFeature"
10+
text: "OpenFeature Web SDK"
11+
- link: "/real_user_monitoring/application_monitoring/browser/"
12+
tag: "Documentation"
13+
text: "Browser Monitoring"
14+
---
15+
16+
{{< callout url="http://datadoghq.com/product-preview/feature-flags/" >}}
17+
Feature Flags are in Preview. Complete the form to request access.
18+
{{< /callout >}}
19+
20+
## Overview
21+
22+
This page describes how to instrument your browser JavaScript application with the Datadog Feature Flags SDK. Datadog feature flags provide a unified way to remotely control feature availability in your app, experiment safely, and deliver new experiences with confidence.
23+
24+
The Datadog Feature Flags SDK for JavaScript is built on [OpenFeature][1], an open standard for feature flag management. This guide explains how to install the SDK, configure the Datadog provider, and evaluate flags in your application.
25+
26+
## Installation
27+
28+
Install the Datadog OpenFeature provider and the OpenFeature Web SDK using your preferred package manager:
29+
30+
{{< tabs >}}
31+
{{% tab "npm" %}}
32+
{{< code-block lang="bash" >}}
33+
npm install @datadog/openfeature-browser @openfeature/web-sdk @openfeature/core
34+
{{< /code-block >}}
35+
{{% /tab %}}
36+
37+
{{% tab "yarn" %}}
38+
{{< code-block lang="bash" >}}
39+
yarn add @datadog/openfeature-browser @openfeature/web-sdk @openfeature/core
40+
{{< /code-block >}}
41+
{{% /tab %}}
42+
43+
{{% tab "pnpm" %}}
44+
{{< code-block lang="bash" >}}
45+
pnpm add @datadog/openfeature-browser @openfeature/web-sdk @openfeature/core
46+
{{< /code-block >}}
47+
{{% /tab %}}
48+
{{< /tabs >}}
49+
50+
## Initialize the provider
51+
52+
Create a `DatadogProvider` instance with your Datadog credentials:
53+
54+
{{< code-block lang="javascript" >}}
55+
import { DatadogProvider } from '@datadog/openfeature-browser';
56+
import { OpenFeature } from '@openfeature/web-sdk';
57+
58+
const provider = new DatadogProvider({
59+
applicationId: '<APPLICATION_ID>',
60+
clientToken: '<CLIENT_TOKEN>',
61+
env: '<ENV_NAME>',
62+
});
63+
{{< /code-block >}}
64+
65+
## Set the evaluation context
66+
67+
Define who or what the flag evaluation applies to using an evaluation context. The evaluation context includes user or session information used to determine which flag variations should be returned. Reference these attributes in your targeting rules to control who sees each variant.
68+
69+
{{< code-block lang="javascript" >}}
70+
const evaluationContext = {
71+
targetingKey: 'user-123',
72+
user_id: '123',
73+
user_role: 'admin',
74+
email: 'user@example.com',
75+
};
76+
77+
await OpenFeature.setProviderAndWait(provider, evaluationContext);
78+
{{< /code-block >}}
79+
80+
<div class="alert alert-info">The <code>targetingKey</code> is used as the randomization subject for percentage-based targeting. When a flag targets a percentage of subjects (for example, 50%), the <code>targetingKey</code> determines which "bucket" a user falls into. Users with the same <code>targetingKey</code> always receive the same variant for a given flag.</div>
81+
82+
## Evaluate flags
83+
84+
After the provider is initialized, you can evaluate flags anywhere in your application. Flag evaluation is _local and instantaneous_—the SDK uses locally cached data, so no network requests occur when evaluating flags.
85+
86+
### Get a client
87+
88+
Retrieve the OpenFeature client to evaluate flags:
89+
90+
{{< code-block lang="javascript" >}}
91+
const client = OpenFeature.getClient();
92+
{{< /code-block >}}
93+
94+
### Boolean flags
95+
96+
Use `getBooleanValue(key, defaultValue)` for flags that represent on/off or true/false conditions:
97+
98+
{{< code-block lang="javascript" >}}
99+
const isNewCheckoutEnabled = client.getBooleanValue('checkout_new', false);
100+
101+
if (isNewCheckoutEnabled) {
102+
showNewCheckoutFlow();
103+
} else {
104+
showLegacyCheckout();
105+
}
106+
{{< /code-block >}}
107+
108+
### String flags
109+
110+
Use `getStringValue(key, defaultValue)` for flags that select between multiple variants or configuration strings:
111+
112+
{{< code-block lang="javascript" >}}
113+
const theme = client.getStringValue('ui_theme', 'light');
114+
115+
switch (theme) {
116+
case 'dark':
117+
setDarkTheme();
118+
break;
119+
case 'light':
120+
default:
121+
setLightTheme();
122+
}
123+
{{< /code-block >}}
124+
125+
### Number flags
126+
127+
Use `getNumberValue(key, defaultValue)` for numeric flags such as limits, percentages, or multipliers:
128+
129+
{{< code-block lang="javascript" >}}
130+
const maxItems = client.getNumberValue('cart_items_max', 20);
131+
const priceMultiplier = client.getNumberValue('pricing_multiplier', 1.0);
132+
{{< /code-block >}}
133+
134+
### Object flags
135+
136+
Use `getObjectValue(key, defaultValue)` for structured configuration data:
137+
138+
{{< code-block lang="javascript" >}}
139+
const config = client.getObjectValue('promo_banner_config', {
140+
color: '#00A3FF',
141+
message: 'Welcome!',
142+
});
143+
{{< /code-block >}}
144+
145+
### Flag evaluation details
146+
147+
When you need more than just the flag value, use the detail methods. These return both the evaluated value and metadata explaining the evaluation:
148+
149+
{{< code-block lang="javascript" >}}
150+
const details = client.getBooleanDetails('checkout_new', false);
151+
152+
console.log(details.value); // Evaluated value (true or false)
153+
console.log(details.variant); // Variant name, if applicable
154+
console.log(details.reason); // Why this value was chosen
155+
console.log(details.errorCode); // Error code, if evaluation failed
156+
{{< /code-block >}}
157+
158+
## Complete example
159+
160+
Here's a complete example showing how to set up and use Datadog Feature Flags in a JavaScript application:
161+
162+
{{< code-block lang="javascript" >}}
163+
import { DatadogProvider } from '@datadog/openfeature-browser';
164+
import { OpenFeature } from '@openfeature/web-sdk';
165+
166+
// Initialize the Datadog provider
167+
const provider = new DatadogProvider({
168+
applicationId: '<APPLICATION_ID>',
169+
clientToken: '<CLIENT_TOKEN>',
170+
env: '<ENV_NAME>',
171+
});
172+
173+
// Set the evaluation context
174+
const evaluationContext = {
175+
targetingKey: 'user-123',
176+
user_id: '123',
177+
user_role: 'admin',
178+
};
179+
180+
await OpenFeature.setProviderAndWait(provider, evaluationContext);
181+
182+
// Get the client and evaluate flags
183+
const client = OpenFeature.getClient();
184+
const showNewFeature = client.getBooleanValue('new_feature', false);
185+
186+
if (showNewFeature) {
187+
console.log('New feature is enabled!');
188+
}
189+
{{< /code-block >}}
190+
191+
## Update the evaluation context
192+
193+
To update the evaluation context after initialization (for example, when a user logs in), use `OpenFeature.setContext()`:
194+
195+
{{< code-block lang="javascript" >}}
196+
await OpenFeature.setContext({
197+
targetingKey: user.id,
198+
user_id: user.id,
199+
email: user.email,
200+
plan: user.plan,
201+
});
202+
{{< /code-block >}}
203+
204+
## Further reading
205+
206+
{{< partial name="whats-next/whats-next.html" >}}
207+
208+
[1]: https://openfeature.dev/
209+

0 commit comments

Comments
 (0)