Use Redux with Flex

In much of your development with the Flex UI, your component state can be informed by information that already lives in Flex - for example, you can get access to the current Task and render the Task data in your custom component.

There are some instances, however, in which adding information to a Task might compromise security, or even just add unnecessary data to the Task itself. In these cases, you can extend the Redux store of your Flex UI and pass the new subscription information to your custom components.

On this page, we’ll cover two strategies for modifying the Flex Redux reducer. The first relies on the Plugin Builder to extend your contact center that’s hosted on flex.twilio.com. The second strategy involves directly modifying the way Flex builds Redux, and is ideal if you’re planning to host Flex on your own infrastructure.

Brief Intro to Redux

Redux is a software package that helps developers manage application state. Flex uses Redux to manage a bunch of application state—for example, a new Task appearing in the UI or an agent changing from Available to Busy are both examples of the application state changing. Redux offers you some nice features:

• A single source of truth about the state of your application (called the store)
• An interface for dispatching Actions that will update the store
• An architecture that makes it easy to test and debug state changes, and, perhaps most importantly,
• An integration with React that allows your React components to subscribe to changes in the store.

Check out the Redux documentation to learn more about all the great features it offers and become a Redux master. You can also get a useful overview of Redux in the Code Cartoon Intro to Redux.

Using Redux in Your Flex Plugin

If you are building your first Flex plugin, you will need to add a new folder and some files to help manage your UI state with Redux.

For the sake of reading this page, the content of the necessary new files is located in the code samples on this page, so don't stress out if you can't set up your first plugin just yet.

Redux Toolkit

Flex 2.0 ships with the immensely helpful Redux Toolkit package, enabling you to create the necessary reducers and Actions to power your Redux-based application state, but without the dreaded boilerplate that is typically associated with Redux.

First you'll see a complete example of a reducer implementation using Redux Toolkit, then we'll break down each major segment so that you may understand how to wrangle Redux on your own.

Define a Slice

Create Actions

In the dark times before Redux Toolkit, you would start this process by first thinking about the shape of your application state, then the Actions that could be dispatched to Redux to initiate changes to that state. This required lots of repetitive boilerplate and SCREAMING_CASE constants, such as:

const SET_OPEN = 'SET_OPEN';

Now, this is necessary to an extent so that Redux is able to uniquely identify your Actions and determine what effect they should have on your state. However, defining and maintaining your own string constants to identify Actions is better left to a library (Redux Toolkit, in this case).

Instead, you can create a Slice, which tells Redux toolkit to automatically define unique Action identifiers on your behalf, and associate them with the corresponding Reducer logic of the same name, all in one function call.

For example, when you see

reducers: {
  setOpen: (state, action) => {...},
},

in the sample code, Redux Toolkit generates an Action with the type of "customTaskList/setOpen". The createSlice function creates Actions by combining the name of the slice, and the name of each case in your Reducer into unique strings.

Now that you have an idea of how to succinctly create an Action, let's look at how you can create a Reducer to handle said Action.

Create a Reducer

You may have seen code like this used to describe a Reducer:

export function reduce(state = initialState, action) {
  switch (action.type) {
    case ACTION_SET_OPEN: {
      return {
        ...state,
        isOpen: action.payload,
      };
    }

    default:
      return state;
  }
}

This is a fundamental of Redux: a Reducer takes your current application state and an Action, and returns an updated state based on the Action.

So, what is the application state? If you'll recall from the first sample code:

const initialState = {
  isOpen: true,
};

This JavaScript object reflects the slice of application state that's modified by this Reducer.

A Reducer is usually one long switch statement, with the various cases that correspond to your different Actions. In this case (ha! See what we did there?) the Reducer deals with two cases: if it sees an Action with the ACTION_SET_OPEN identifier, it changes the isOpen value to whatever boolean value was passed to the Action. Otherwise, if it doesn't recognize the Action identifier (or there isn't one), it'll just maintain the current application state and your UI will not update.

You might also notice that the Reducer is creating a brand-new state each time it is executed, instead of breaking immutability by directly changing the value of isOpen. The Reducer does this by using the spread operator to clone the existing state, spread its properties to a new object, and then inject a value for isOpen that will override the previous value. This works and is how Reducers have been written for years. However, this results in creating brand-new objects every time the Reducer runs (which could pose performance penalties if done frequently enough). Also, while the syntax doesn't look too messy in this example, it can quickly become a mess if you need to update a property located several levels deep in the state object.

With the createSlice API from Redux Toolkit, you define your Reducer's logic at the same time as you create the associated Action. Not only that, but you might have noticed that the Reducer is directly mutating the state object:

reducers: {
  setOpen: (state, action) => {
    state.isOpen = action.payload;
  },
},

Now, technically this code is still immutable, and it isn't directly mutating state (which would prevent Redux from detecting any changes or updating your UI, yikes!). This is because Redux Toolkit uses Immer under the hood to manage Redux state, and the value of state in each Reducer function is actually an Immer Draft. If you're using TypeScript, you can hover over state and see that it is type WritableDraft<CustomTaskListState>, not merely CustomTaskListState.

What this means is:

• You can now quickly define your Reducers as a collection of functions that take state and action as arguments (already a Redux pattern)
• You may use mutative operations in your Reducers, which means cleaner syntax and less noisy Reducer code
• You can access unique string identifiers for your Actions by name from the result of createSlice (syntax shown in the sample)

What exactly is all of this code accomplishing?

First, the index file serves as a place to import all of your Reducers, and combine them into a single Reducer which can be added to Flex, as well as creating a helpful mapping of all Actions. If you're using TypeScript, it's also an excellent place to create an overall typed interface for your Application state and Actions, which will lead to fantastic autocomplete when accessing your state (and Actions) in your React components.

Next, your plugin file imports your Reducer, and adds it to the existing Flex UI Redux store so that it is accessible across your entire application and by other potential plugins. It does so by using the manager.store.addReducer method, which registers the given reducer under the provided namespace key.

That's great, but how can you now access that state, and dispatch Actions to modify it from your app? Let's cover that now.

Access Redux from your Plugin Component(s)

Now that your Reducer logic is defined and integrated with Flex, you need to connect all of that logic to the UI. In the Plugin Builder sample app, this will happen in the existing src/components/CustomTaskList/CustomTaskList.tsx (or .jsx) file.

Like with the Redux sample, let's start with the complete code, and break it down:

Access and use state

When it comes to accessing Redux state, there is a best practice of using Selectors. Selectors allow you to efficiently access values within your Redux state, and will only tell your React component to re-render if the value targeted by the selector is changed by an Action.

Nowadays, it is best practice to leverage the useSelector hook to access state. (In older codebases, this is similar to the mapStateToProps function for connect, but we don't live in those times anymore, thankfully)

You can see this in action inside the component, here:

  const isOpen = useSelector(
    (state: AppState) => state.pluginState.customTaskList.isOpen
  );

With the useSelector hook, the component is able to access the full Redux store, then the plugin's namespace (which we named pluginState earlier), and so on until you have the value needed by your component's logic. If you are using TypeScript and defined your state types earlier, this entire process will be typed and provide excellent autocomplete to speed up development.

You can then do any valid TypeScript/JavaScript action based on that value, such as conditionally preventing rendering of the component:

if (!isOpen) {
  return null;
}

Access and dispatch Actions

To update Redux state, you must dispatch Actions to Redux. You can gain access to the dispatch method, which enables you to dispatch Actions, from any React component by using the useDispatch hook. You can see this pattern in the CustomTaskList component example:

const dispatch = useDispatch();

const dismiss = () => dispatch(actions.customTaskList.setOpen(false));

In order to dispatch an Action, call dispatch with that Action as an argument, and provide the Action with whatever payload it might require (not all Actions require a payload). Redux will notice the dispatched Action, grab any attached payload (and error or meta properties, if defined), and execute the related reducer function to update your app's state.

Similar to state, if you are using TypeScript and were careful to type your Actions, your Action creators will provide autocompletion as well as errors if you provide a mistyped payload.

As you can see, Redux helps you create a distributed flow of data through your whole plugin. The user interacts with the UI component, which invokes the dispatch function. The dispatch function sends out the relevant Action, which is observed by the reducers. The reducer takes whatever information is associated with that Action and modifies the Redux Store to reflect what’s going on. At long last, the UI component, which is subscribed to the Redux Store, detects a new state and re-renders to reflect the new application state!

Redux has a complex data flow, but once you've mastered it, it makes reasoning about and testing complex apps—like the UI for an Omnichannel Contact Center—much easier. Thanks to tools like Redux Toolkit, this process is significantly faster and loaded with less boilerplate than it used to be, as well.

Add more state to the Redux Store

You are free to modify and add more state to your Plugin's component. Inside src/states/CustomTaskListState.ts (or .js), update the type definition (if applicable) of your state, and define a new counter in your initialState object called taskCounter.

Next, update the existing call to createSlice to include a new Action/Reducer pair that increments the task counter, the updated reducer will look like this:

With the reducer updated, you will need to make a few tiny adjustments to the src/states/index file so that it will export the new Action that you just created. You'll notice that the only change here is the added import of incrementTasks, and its addition to the actions map.

Alright, now that the reducer and Actions are updated, they can be referenced and used by your CustomTaskList component. Open the CustomTaskList component once again.

Now, you'll add a new selector to track the counter value, some new JSX to render the counter and a button, and use the button to dispatch new incrementTasks Actions.

Your plugin now has multiple state values in Redux, and components that not only react to state changes, but are able to update the state as well from anywhere in the component tree.

Write asynchronous Actions

Managing local state is a great use case for Redux, but most applications involve asynchronous code that takes some time to complete, like network requests.

Flex UI includes the redux-promise middleware, which enables you to dispatch Actions with asynchronous behavior.

Suppose you want to have an Action that, when dispatched, triggers a request for an image, which then is saved to your state and rendered in the UI. You also want to communicate to your user that something is in progress, say, with a spinner.

An example looks like this:

// Helper method that returns a promise, which will resolve to a
// dog image URL
const getCompanion = async () => {
  const response = await fetch('https://dog.ceo/api/breeds/image/random');
  const data = await response.json();
  return data.message;
};

// We're manually creating a Redux Action in this instance, so
// define a unique string identifier for the fetch dog Action
const FETCH_DOG = 'customTaskList/fetchDog';
export const fetchDog = () => {
  return {
    type: FETCH_DOG,
    payload: getCompanion(),
  };
};

Without the presence of redux-promise-middleware, dispatching this Action would case your app to throw an error and crash. That's because this Action doesn't return an object containing a type and an image string as the payload -- the payload is a Promise which will resolve to the image string at some point in the future. By default, Redux only accepts plain objects, no Promises.

Thankfully, Flex's inclusion of redux-promise-middleware, means that this type of Action is valid to dispatch. The middleware intercepts any Actions that contain a Promise, and replaces them with a sequence of pending, fulfilled, or rejected Actions that reflect each state of a Promise.

First, it will dispatch a pending Action, which is useful for rendering loading spinners and letting your user know that something is happening. Next, if the Promise resolves successfully, it will dispatch a fulfilled Action containing whatever data the Promise returns. Otherwise, the Promise ran into a failure, and the middleware will dispatch a rejected Action which contains information related to the error that occurred.

Assuming your original Action had a type of 'FETCH_DOG', the three replacement Actions that redux-promise-middleware will generate are:

• 'FETCH_DOG_PENDING'
• 'FETCH_DOG_FULFILLED'
• 'FETCH_DOG_REJECTED'

Let's look at how you would modify your CustomTaskListState to take advantage of this behavior:

This update to the code introduces:

• A new asynchronous Action fetchDog
• Additional state for tracking the image URL and loading state
• Extra cases to the reducer logic, to handle each of the three middleware-generated Actions.

You might be wondering about this new extraReducers property that's been added to the Slice. You can read more about it in the official Redux Toolkit docs, but essentially extraReducers is how you add extra cases to the reducer that you're creating, even if the Action wasn't created by the same Slice.

The Action has been created, and your reducer knows how to handle every variation of the request that it creates. To see this in... action, you'll need to update your UI to dispatch this new Action:

In short, this updated component pulls in the new values from Redux, dispatches the new Action when it appears in the UI, and includes some new rendering logic to keep the UI responsive to the network request.

If you reload your plugin with this updated code, you should very briefly see a spinner appear in the UI before it is replaced with a cute dog avatar. Asynchronous Redux at its finest.

You may apply this pattern in your app in a variety of ways, such as firing requests on button clicks, or triggering timers as a user navigates between routes.

Combine Your Application's Reducer and the Flex UI's Reducer

If you've built your own Redux application, you can extend your own UI to include all of the stateful goodness in Flex. This option is only recommended if you already have an existing React app - otherwise, Plugins are likely a better choice. The following sample code is a brief example of how you can integrate Flex into your own application.

import React from 'react';
import ReactDOM from 'react-dom/client';
import {
  applyMiddleware,
  combineReducers,
  compose,
  createStore
} from '@reduxjs/toolkit';
import Flex from '@twilio/flex-ui';

import myReducer from './myReducerLocation';
import configuration from './appConfig';

// Use Redux's combineReducers method to add
// the Flex reducer to your existing reducers
const reducers = combineReducers({
  app: myReducer,
  flex: Flex.FlexReducer,
});

// Define any of your own middleware(s)
const middleware = applyMiddleware();

// Build a Redux store using the combined reducers and middlewares
const store = createStore(
  reducers,
  compose(middleware, Flex.applyFlexMiddleware())
);

// Flex is instantiated with the new Redux store,
// which includes your custom reducers
Flex.Manager.create(configuration, store).then((manager) => {
  const root = ReactDOM.createRoot(document.getElementById('root'));
  root.render(
    <Provider store={store}>
      <Flex.ContextProvider manager={manager}>
        <Flex.RootContainer />
      </Flex.ContextProvider>
    </Provider>
  );
});

What Next?

• Now that you're familiar with Redux, learn more about how Flex uses React
• Check out how to fetch data from a Plugin and add that data to your Redux store.
• Learn how to deploy your Plugin