Add Bloomreach SDK to a React App



Add the Bloomreach React SDK to an existing React application.


Bloomreach Content comes with a sample React frontend application ("Pacific Nuts & Bolts") which can be used to follow the tutorials and as a starting point for your developing own frontend application. However, you may already have an existing React frontend you want to integrate Bloomreach Content with or you may want to start from scratch.

This page describes the steps required to add the Bloomreach React SDK to the default app created by Create React App.

Create React App

Following instructions from, create your app using:

npx create-react-app <my app name>

Change into the newly created directory :

cd <my app name>

Add Bloomreach SDK Packages

Install the required packages using npm:

npm install @bloomreach/react-sdk @bloomreach/spa-sdk axios react-router-dom

Start the application:

npm start

Confirm that the default React app at http://localhost:3000 loads in your browser.

Edit React Source Files

Change index.js to look like this:

import React from 'react';
import ReactDOM from 'react-dom';
import { BrowserRouter, Redirect, Route, Switch } from 'react-router-dom';
import './index.css';
import App from './App';
       <Route path="/(.*)" component={App} />
        <Redirect to="/" />

What you’ve done here is to use index.js to handle routing and send everything to the main App component.

Then change App.js to look like this:

import React from 'react';
import { BrComponent, BrPage } from '@bloomreach/react-sdk';
import Content from './Content';
import './App.css';
import axios from 'axios';
function App({ location }) {
 const configuration = {
   baseUrl: 'http://localhost:3000',
   endpointQueryParameter: 'endpoint',
   httpClient: axios,
   request: {
     path: `${location.pathname}${}`,
 const mapping = {
 return (
   <BrPage configuration={configuration} mapping={mapping}>
     <BrComponent path="main">
       <div className="App">
         <BrComponent />
export default App;

There are a number of important things happening here:

  • You are defining the configuration object, passing in important information:
    • baseUrl: this is where your app is running (locally).
    • endpoint: this should point to the Delivery API's Pages endpoint for your Bloomreach Content environment. It should look something like this: https://<your_env>
    • request : path - this should not be changed from the example above. The value contains important token variables when in the context of the Experience manager application allowing for preview and component management functionality.
  • You are defining a mapping object which is used to map components in Bloomreach Content to your actual React components. Note that you are mapping a component called Content. This is both a React Component in your application (you will define that next, see below), as well as a component you will find as being defined in the site configuration in your Commerce Experience Cloud environment.
  • You have added JSX which handles rendering everything defined in Bloomreach Content. For example, you expect to render a section called main. The <BrComponent /> element within that main section will handle rendering all content components found in that section.

When you save all of these files, you will see an error message like "Module not found: Can’t resolve ‘./Content’ in ‘...’" in your browser. This is expected - you need to add this file to the /src folder. Here’s what the Content.js file should look like:

import React from 'react';
import { BrManageContentButton } from '@bloomreach/react-sdk';
const Content = ({ page }) => {
 const document = page.getDocument();
 const { content, image: imageRef, title } = document.getData();
 const image = imageRef && page?.getContent(imageRef)?.getOriginal();
 return (
       page.isPreview() ? 'has-edit-button' : ''
     } mw-container mx-auto`}
     <BrManageContentButton content={document} />
     <br />
     {title && <h1 className="mb-4">{title}</h1>}
     {content?.value && (
           __html: page?.rewriteLinks(content.value) ?? '',
     {image && (
         <img src={image.getUrl()} alt={title} width="100%" />
export default Content;

Now, when you save Content.js, you should see no React errors.

However, if you are looking at the homepage URL (http://localhost:3000/), most likely you are seeing several messages about components not being found. This is expected, as the homepage is a landing page containing a number of components which are not mapped and defined as React components in your React application.

For a better result, load one of the article pages (for example, http://localhost:3000/articles/changing-a-tap-washer). This is a content page that uses the Content component which you just defined in your React application. The article content should be rendered on the page.

The Content.js file is grabbing some data about the actual content (image, title, content, etc.), and rendering that data.  You can modify this component to style things any way you want.  You will also notice the <BrManageContentButton … />. This only shows up when editing the content within the Experience manager application.

Next Steps

A logical next step would be to map more Bloomreach Content components to React components in your app so that it can render them.

You can inspect the Delivery API output for each page to find out all the different componets (for details on the response format see Pages JSON Representation. For example:

  • Homepage: https://<your_env>
  • Article page: https://<your_env>

Refer to the Sample React App for sample implementations of all default Bloomreach Content components - you can even copy them to your own app.

Once you app is able to render all the components, you can start using the Site Management API to modify the site configuration and define your own components, layouts, routes, etc.