mirror of
https://github.com/Unleash/unleash.git
synced 2025-01-25 00:07:47 +01:00
c44601b33c
<!-- Thanks for creating a PR! To make it easier for reviewers and everyone else to understand what your changes relate to, please add some relevant content to the headings below. Feel free to ignore or delete sections that you don't think are relevant. Thank you! ❤️ --> ## About the changes <!-- Describe the changes introduced. What are they and why are they being introduced? Feel free to also add screenshots or steps to view the changes if they're visual. --> We've made some first round updates to the React tutorial: - making it more SEO-friendly with ordered lists, sequential language, description of the JS library - Switched over the demo app to point to an open source project: [Cypress Real World App](https://github.com/cypress-io/cypress-realworld-app) - included best practice considerations for client-side development - updated URL path to point to `/feature-flag-tutorials/react` for simplification ## Discussion points <!-- Anything about the PR you'd like to discuss before it gets merged? Got any questions or doubts? --> Would love feedback on if there's a need for more screenshots? Don't want to be too screenshot-heavy though I imagine. And need feedback on the descriptions of "Considerations for using feature flags in react" https://github.com/Unleash/unleash/compare/react-improvements?expand=1#diff-96d4956f49f80cd76489a72d4d88c2956ce9dcc695f66fe014ad1185e37cb589R21 Want to make sure that what I described makes sense or if it could use some tweaking to convey the right message clearly.
273 lines
13 KiB
Markdown
273 lines
13 KiB
Markdown
---
|
||
title: How to Implement Feature Flags in React
|
||
slug: /feature-flag-tutorials/react
|
||
---
|
||
|
||
[React](https://react.dev/) is a popular JavaScript library utilized by millions of developers across the world to build user interfaces for frontend, mobile, or server-side applications when paired with frameworks. Originally developed by Meta, React has a strong community and is best used for interactive, complex, SEO-friendly application development.
|
||
|
||
Leveraging feature flags allows you to toggle on and off new features you’re developing, whether you’re experimenting in your local environment, testing for QA purposes, or rolling out to users in production. It can play a critical part in optimizing the entire software development lifecycle. With Unleash, you can use our tooling to implement feature flags into your application and release new features faster, strategically, and safely. But how can you do this in React?
|
||
|
||
[Cypress Real World App](https://github.com/cypress-io/cypress-realworld-app) is an open source React project that allows you to test and experiment in a React codebase that mirrors a real world use case: a financial transaction application. It harnesses Cypress for testing, Material UI for CSS, a built-in database, and other tools to provide a fully functioning application experience for educational purposes.
|
||
|
||
|
||
|
||
In this tutorial, you will learn how to set up and use React feature flags with Unleash. We will be using the Cypress Real World App to implement the feature flag solution, which will simulate how you can gradually roll out a notifications feature to users. At the end of this tutorial, you'll be able to enable on the flag you create and launch the notification icon, making it visible for a percentage of users to click on and be taken to a Notifications view to see transaction updates from user contacts.
|
||
|
||
Along the way, you will:
|
||
|
||
1. [Spin up a local instance of Unleash](#1-install-and-run-unleash-on-your-local-machine)
|
||
2. [Create a feature flag](#2-create-and-enable-a-feature-flag)
|
||
3. [Generate an API token](#3-generate-an-api-token)
|
||
4. [Clone a React app](#4-clone-an-open-source-react-app)
|
||
5. [Set up Unleash in your app](#5-set-up-unleash-in-your-app)
|
||
6. [Toggle the visibility of a feature component](#6-use-the-feature-flag-to-rollout-a-notifications-badge)
|
||
7. [Verify the toggle experience](#7-verify-the-toggle-experience)
|
||
|
||
|
||
## Considerations for using feature flags with React
|
||
|
||
|
||
We recommend that you reduce sensitive user data exposure by conducting feature flag evaluations in a self-hosted environment. Evaluating on the client side in a React application could potentially **[expose sensitive data](https://docs.getunleash.io/topics/feature-flags/never-expose-pii)** such as API keys, flag configurations and flag data. A server-side evaluation of feature flags is recommended practice for privacy protection, as it will minimize sending data to the Feature Flag Control Service and reduce the attack surface of your application/services.
|
||
|
||
|
||
## Prerequisites
|
||
|
||
|
||
In this tutorial, you will need the following:
|
||
|
||
- A web browser like Chrome or Firefox
|
||
- Git
|
||
- Docker
|
||
- NPM, Node and Yarn to install and run a React app
|
||
- (Optional) A code editor like Visual Studio Code
|
||
|
||
|
||
|
||
|
||
|
||
### 1. Install and run Unleash on your local machine
|
||
|
||
|
||
In this section, you will install Unleash in order to run it, log in, and create a feature flag. You will use Git to clone the Unleash repository and Docker to build and run it.
|
||
|
||
Open a terminal window and run the following commands:
|
||
|
||
```
|
||
git clone git@github.com:Unleash/unleash.git
|
||
cd unleash
|
||
docker compose up -d
|
||
```
|
||
|
||
You will now have Unleash installed onto your machine and running in the background.
|
||
You can access this instance in your web browser at [http://localhost:4242](http://localhost:4242/)
|
||
|
||
Log in to the platform using these credentials:
|
||
|
||
```
|
||
Username: admin
|
||
Password: unleash4all
|
||
```
|
||
|
||
The unleash platform shows a list of feature flags that you’ve generated. Click on the ‘New Feature Toggle’ button to create a new feature flag.
|
||
|
||
|
||
|
||
|
||
### 2. Create and enable a feature flag
|
||
|
||
|
||
Next, you will create a feature flag on the platform and turn it on for your React app.
|
||
|
||
> **Note:** This document uses feature flags and feature toggles interchangeably. Some people prefer flag; others prefer toggle. We use both - they are synonyms for us.
|
||
|
||
In the [Create Toggle view](http://localhost:4242/projects/default/create-toggle/), give your feature flag a unique name and click ‘Create toggle feature’.
|
||
|
||
For the purpose of this tutorial, you won’t need to change the default values in the rest of the feature flag form.
|
||
|
||
Your new feature flag is created and ready to be used. Enable the flag for your development environment, which makes it accessible to be used in the React app we will generate from your local environment.
|
||
|
||
|
||
|
||
|
||
Your new feature flag is created and ready to be used. Enable the flag for your development environment, which makes it accessible to be used in the React app we will generate from your local environment.
|
||
|
||
|
||
|
||
|
||
### 3. Generate an API token
|
||
|
||
|
||
Next, you will generate an API token to authenticate calls made to Unleash servers to access and use the feature flag in your project. This API token will eventually be pulled into a configuration object within your React application to toggle features.
|
||
|
||
From your project view on the platform, click on [Project Settings](http://localhost:4242/projects/default/settings/environments) and then [API Access](http://localhost:4242/projects/default/settings/api-access).
|
||
|
||
Click on the ‘New API token’ button.
|
||
|
||
|
||
|
||
Name the API token and connect to the Client-side SDK.
|
||
|
||
The token should have access to the “development” environment, as shown in the platform screenshot below.
|
||
|
||
|
||
|
||
The API token you have generated can be managed in the API Access view in your project settings. This token will come in handy in Step 5.
|
||
|
||
|
||
### 4. Clone an open source React app
|
||
|
||
|
||
In this section, you will clone an open source React application called [Cypress Real World App](https://github.com/cypress-io/cypress-realworld-app), which is meant to model what a more complex, real life use case would be for a fully-functioning app to experiment in.
|
||
|
||
This project leverages many libraries and frameworks to handle the user interface, functionality, database, authentication, and testing of a financial transaction app. These frameworks include Express, Material-UI, Cypress, TypeScript and more.
|
||
|
||
Go to your Terminal and clone the repository with this command:
|
||
|
||
```
|
||
git clone git@github.com:cypress-io/cypress-realworld-app.git
|
||
```
|
||
|
||
> :triangular_flag_on_post: **Note:**
|
||
Since Yarn is required in order to run the app, make sure you have it installed globally. If you do not, run the command below.
|
||
|
||
```
|
||
npm install yarn@latest -g
|
||
```
|
||
|
||
In your app's directory, begin installing the dependencies and then run the app:
|
||
|
||
```
|
||
yarn
|
||
yarn dev
|
||
```
|
||
|
||
> **Note**: We recommend using the default ports that exist in the app's configurations, which are explained in the [README](https://github.com/cypress-io/cypress-realworld-app?tab=readme-ov-file#run-the-app) for it to point to. In order to ensure those function as expected, make sure no other apps are running on your machine that also port to `localhost:3000` and `localhost:3001`.
|
||
|
||
In your browser at `http://localhost:3000`, you will be directed to the sign-in page of the Cypress Real World App.
|
||
Utilize one of the pre-existing user accounts from the database to sign in.
|
||
|
||
```
|
||
Username: Allie2
|
||
Password: s3cret
|
||
```
|
||
|
||
For more detailed instructions on the setup process for this app, review the [README](https://github.com/cypress-io/cypress-realworld-app?tab=readme-ov-file#getting-started).
|
||
|
||
|
||
### 5. Set up Unleash in your app
|
||
|
||
|
||
It’s time to pull in your newly created feature flag in your app. Run the following command to install the Unleash React SDK in your repo:
|
||
|
||
```
|
||
yarn add @unleash/proxy-client-react unleash-proxy-client
|
||
```
|
||
|
||
Once Unleash has been installed, open up a code editor like VSCode to view your React repo.
|
||
|
||
In `src/index.tsx`, import the `<FlagProvider>`:
|
||
|
||
```js
|
||
import { FlagProvider } from "@unleash/proxy-client-react";
|
||
```
|
||
|
||
Paste in a configuration object:
|
||
|
||
```js
|
||
const config = {
|
||
url: "http://localhost:4242/api/frontend", // Your local instance Unleash API URL
|
||
clientKey: "<client_key>", // Your client-side API token
|
||
refreshInterval: 15, // How often (in seconds) the client should poll the proxy for updates
|
||
appName: "cypress-realworld-app", // The name of your application. It's only used for identifying your application
|
||
};
|
||
```
|
||
|
||
In the `Router` section of this file, wrap the `FlagProvider` around the existing `<App />` component:
|
||
|
||
```js
|
||
<FlagProvider config={config}>
|
||
<App />
|
||
</FlagProvider>
|
||
```
|
||
|
||
Next, replace the `<client_key>` string in the config object with the API token you generated. You can do this by copying the API token into your clipboard from the API Access view table and pasting it into the code.
|
||
|
||
This configuration object is used to populate the `FlagProvider` component that comes from Unleash and wraps around the application, using the credentials to target the specific feature flag you created for the project.
|
||
|
||
You can find more documentation on Unleash API tokens and client keys [here](https://docs.getunleash.io/reference/api-tokens-and-client-keys#front-end-tokens).
|
||
|
||
Additionally, we have documentation on using the [Client-Side SDK with React](https://docs.getunleash.io/reference/sdks/react) for advanced use cases.
|
||
|
||
|
||
### 6. Use the feature flag to rollout a notifications badge
|
||
|
||
In a real world use case for your feature flag, you can gradually rollout new features to a percentage of users by configuring the flag's strategy.
|
||
|
||
In this case, we want to rollout a new notifications badge that will appear in the top navigation bar so users can see the latest updates from transactions between contacts. This will require us to modify the visibility of a React component that is rendered in our app.
|
||
|
||
In `src/components/NavBar.tsx`, import the `useFlag` feature:
|
||
|
||
```js
|
||
import { useFlag } from "@unleash/proxy-client-react";
|
||
```
|
||
|
||
Within the `NavBar` component in the file, define and reference the flag you created.
|
||
|
||
```js
|
||
const notificationBadgeEnabled = useFlag("newNotificationBadge");
|
||
```
|
||
|
||
This flag will be used to conditionally render the notification icon `Badge` that is pulled in from Material-UI.
|
||
If the flag is enabled, the notification badge will display to users and will route them to the Notifications view.
|
||
|
||
Find the `Badge` component in the file and wrap it in a boolean operator:
|
||
|
||
```js
|
||
{notificationBadgeEnabled && (
|
||
<Badge
|
||
badgeContent={allNotifications ? allNotifications.length : undefined}
|
||
data-test="nav-top-notifications-count"
|
||
classes={{ badge: classes.customBadge }}
|
||
>
|
||
<NotificationsIcon />
|
||
</Badge>
|
||
)}
|
||
```
|
||
|
||
> **Note:** Ensure you have the correct format in your file or the Prettier formatter will display an error.
|
||
|
||
|
||
### 7. Verify the toggle experience
|
||
|
||
|
||
In your Unleash instance, you can toggle your feature flag on or off to verify that the different UI experiences load accordingly.
|
||
|
||
|
||
|
||
Enabling the flag will result in being able to see the notifications icon in the top menu of the app.
|
||
|
||
|
||
|
||
You can adjust the percentage of users that get to view this experience through our gradual rollout feature. The percentage of users who are split up between the notification feature being visible or not is cached so their user experience will remain consistent. Navigate to the Gradual Rollout form in Unleash by clicking on "Edit strategy".
|
||
|
||
|
||
|
||
Adjust the percentage of users to 50% or whichever percentage you choose and refresh your app in the browser to see if your user is opted in to the new feature experience.
|
||
|
||
|
||
|
||
Learn more about [gradual rollouts in our docs](https://docs.getunleash.io/reference/activation-strategies).
|
||
|
||
If you disable the flag, this results in a view of a navigation menu without the notification badge for **all** users.
|
||
|
||
|
||
|
||
|
||
You've successfully implemented a feature flag using best practices to control the release of a notifications feature in a real world app!
|
||
|
||
|
||
### Conclusion
|
||
|
||
In this tutorial, you learned how to install Unleash onto your machine, create a new feature flag, install Unleash into a React app and toggled the visibility of a notifications feature. You also implemented the gradual rollout activation strategy for users in a [real world open source project](https://github.com/cypress-io/cypress-realworld-app)!
|
||
|