Skip to content

Commit 5d99403

Browse files
MargoBGHMargoBGH
authored
Merge pull request #15 from cloudbees-io/MargoBGH-patch-1
[CBP-16193] Update react-fm-example
2 parents cbf8edd + 9ad49ce commit 5d99403

File tree

1 file changed

+103
-80
lines changed

1 file changed

+103
-80
lines changed

‎README.adoc‎

Lines changed: 103 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,117 +1,140 @@
1-
= Example React application for CloudBees platform feature management
1+
# Example React application for CloudBees platform feature management
22

3-
Use this example application to integrate with the CloudBees platform and test out feature management.
4-
After integrating, watch the application display change in response to any updates you make to flag values in the platform.
3+
Use this example application to integrate with the CloudBees platform and test feature management. After integrating, observe changes in the application UI as you update flag values in the platform.
54

6-
In the example application, the ROX package is already set up, and feature flags are already coded in.
5+
In this example, the Rox SDK is already set up, and feature flags are implemented in the code.
76

7+
---
88

9-
[#add-key]
10-
== Integrate the example application with the platform
9+
## Get started with the React project
1110

12-
Your SDK key is a link:https://docs.cloudbees.com/docs/cloudbees-platform/latest/feature-management/learn-about-feature-flags[unique environment identifier].
13-
The SDK key is displayed in the SDK installation instructions in the platform UI.
14-
To successfully install the SDK, you must copy the SDK key for that environment into your application at the Rox setup call, save the file, and run the application.
11+
To get started with the `react-fm-example` project, follow these steps:
1512

16-
To save your SDK key in the example application:
13+
### 1. Clone the example repository
1714

18-
. Go to *Feature management* > *Installation* in the platform UI.
19-
. Select an environment (or create a new one).
20-
. Select the appropriate SDK.
21-
. Copy the environment-specific SDK key located within the `Rox.setup` call.
15+
```bash
16+
git clone git@github.com:cloudbees-io/react-fm-example.git
17+
```
2218

23-
+
24-
[cols="2a,2a,1a,4a",options="header"]
25-
.Location of SDK key placeholder in the React app
26-
|===
27-
| Example app repository
28-
| File path
29-
| Line number
30-
| Line
19+
### 2. Open the project
3120

32-
| link:https://github.com/cloudbees-io/react-fm-example[react-fm-example]
33-
| src/feature-management/FeatureFlagsProvider.tsx
34-
| 7
35-
| `const sdkKey = '<YOUR-SDK-KEY>'`
21+
Use your preferred IDE (for example, Visual Studio Code, WebStorm, or IntelliJ IDEA).
3622

37-
|===
23+
### 3. Locate and copy the SDK key in the CloudBees platform
3824

39-
+
40-
. Replace the example app placeholder (`<YOUR-SDK-KEY>`) with your copied key.
41-
. Save the file in the repository.
25+
1. In the CloudBees platform, go to **Feature management > Flags**.
26+
2. Select an application.
27+
3. Select the **copy** icon next to the SDK key.
4228

43-
The SDK key is generated for your environment, and copied into the example application.
44-
To learn more, refer to the SDK installation instructions in the platform UI or in link:https://docs.cloudbees.com/docs/cloudbees-platform/latest/install-sdk/[the documentation].
29+
> **Note:**
30+
> If no SDK key is available:
31+
> 1. In the platform, go to **Feature management > Flags**.
32+
> 2. Select the **installation instructions** icon.
33+
> 3. Follow the installation steps. The SDK key appears once an application is linked to an environment.
34+
> 4. Close the installation panel and copy the SDK key.
4535

46-
[#run]
47-
== Run the application
36+
### 4. Add the SDK key to the React application
4837

49-
After saving your SDK key in the example application, run the example application.
38+
Open the following file:
5039

51-
Run one of the following in the terminal:
40+
```
41+
src/feature-management/FeatureFlagsProvider.tsx
42+
```
5243

53-
* For Yarn package manager:
54-
+
55-
[source,bash]
56-
----
44+
Replace the placeholder with your SDK key, for example:
45+
46+
```tsx
47+
const sdkKey = "<YOUR-SDK-KEY>";
48+
```
49+
50+
Save the file.
51+
52+
---
53+
54+
## Run the application
55+
56+
You can use either Yarn or NPM.
57+
58+
### Yarn
59+
60+
```bash
5761
yarn install
5862
yarn dev
59-
----
63+
```
6064

61-
* For NPM package manager:
62-
+
63-
[source,bash]
64-
----
65+
### NPM
6566

67+
```bash
6668
npm install
6769
npm run dev
68-
----
70+
```
71+
72+
After the application starts, open the URL displayed in your terminal to view the running application.
73+
74+
To verify integration, return to the SDK installation panel in the CloudBees platform UI and select **Test integration**.
75+
76+
---
77+
78+
## View the imported flags
79+
80+
Now that your application is running:
81+
82+
1. In the CloudBees platform, select **Feature management**.
83+
2. Select your example application to view the imported feature flags.
84+
85+
### Feature flags in this example
86+
87+
| Flag name | Type | Description |
88+
|---------------|---------|-----------------------------------------------------------------|
89+
| **showMessage** | Boolean | Turns the message on or off. |
90+
| **message** | String | Sets the message text. |
91+
| **fontSize** | Number | Font size in pixels. Values: `12`, `16`, or `24`. |
92+
| **fontColor** | String | Font color. Values: `red`, `green`, or `blue`. |
6993

70-
Then go to the provided URL to display the running application.
94+
> **Note:**
95+
> If no flags are displayed, verify that the environment-specific SDK key is correctly added in
96+
> `src/feature-management/FeatureFlagsProvider.tsx`.
97+
> Save the file and restart the application.
7198

72-
TIP: After you have the example application running, select *TEST INTEGRATION* in Step 5 of the SDK installation in the platform UI to check if your integration is successful.
99+
---
73100

74-
== Use the platform to update flag values
101+
## Update flag values in the platform UI
75102

76-
Now that your application is running, go to your environment in *Feature management* to display the flags available in the example application:
103+
1. Select **Feature management**.
104+
2. Select the application.
105+
3. Select the **vertical ellipsis** next to a flag.
106+
4. Select **Configure**.
107+
5. Select the environment associated with your SDK key.
108+
6. Update the flag value and save your changes.
109+
7. Set **Configuration status** to **On**.
77110

78-
[cols="1a,1a,4a",options="header"]
79-
.Feature flags in the example application.
80-
|===
111+
The updated flag value will appear in the application shortly.
81112

82-
| Flag name
83-
| Flag type
84-
| Description
113+
---
85114

86-
| `showMessage`
87-
| Boolean
88-
| Turns the message on or off.
115+
## Use the application with multiple SDK keys
89116

90-
| `message`
91-
| String
92-
| Sets the message text.
117+
You can run multiple SDK instances in one application, each with its own SDK key and environment. Each instance is isolated. Use this when you need to:
93118

94-
| `fontSize`
95-
| Number
96-
| Sets the font size in pixels.
97-
The flag value has the following variations: `12`, `16`, or `24`.
119+
- Compare flags across environments without redeploying
120+
- Support multi-tenant routing
121+
- Combine server-side and client-side evaluations
98122

99-
| `fontColor`
100-
| String
101-
| Sets the font color. The flag value has the following variations: `red`, `green`, or `blue`.
123+
To use multiple SDK keys:
102124

103-
|===
125+
1. Retrieve the SDK keys for the environments you will use.
126+
2. Initialize a separate SDK instance for each key.
127+
3. Route requests to the appropriate instance (for example, by tenant or region).
128+
4. Perform register/fetch/stream setup on each instance as required by the SDK.
129+
5. Evaluate flags using the correct instance and a consistent user/context object.
130+
6. Tag logs or metrics by instance and shut down instances when not needed.
104131

105-
NOTE: If no flags are displayed, check that the environment-specific SDK key is <<add-key,correctly added to the example application>>.
132+
---
106133

107-
To update flags in the platform UI:
134+
## Documentation reference
108135

109-
. Select *Feature management* from the left pane.
110-
. Select the vertical ellipsis icon next to the flag you want to configure.
111-
. Select *Configure*.
112-
. Select the *Environment* you used for copying the SDK key.
113-
. Update a flag value and save your changes.
114-
. Switch the *Configuration status* to *On*.
136+
- JavaScript SDK installation:
137+
https://docs.cloudbees.com/docs/cloudbees-platform/latest/install-sdk/javascript-sdk
115138

116-
The updated flag value is soon reflected in the display of the application.
117-
For more information on setting flag values, refer to the link:https://docs.cloudbees.com/docs/cloudbees-platform/latest/feature-management/configure-feature-flags[flag configuration documentation].
139+
- Configure feature flags:
140+
https://docs.cloudbees.com/docs/cloudbees-platform/latest/feature-management/flag-configuration

0 commit comments

Comments
 (0)