Upgrade to Bloomreach Content React SDK 14

This guide explains how to migrate your React project from bloomreach-experience-react-sdk (for brXM 13) to @bloomreach/react-sdk (for brXM 14).

Configuration

Before updating your application code, configure @bloomreach/react-sdk in your project.

1. Install @bloomreach/react-sdk using the instructions in the installation documentation.

2. Update your environment configuration in the .env file as described in the SPA SDK configuration documentation.

   For applications based on create-react-app:

   PUBLIC_URL=http://localhost:3000
   
   REACT_APP_LIVE_BR_BASE_URL=http://localhost:8080/site/spa-channel
   REACT_APP_LIVE_SPA_BASE_URL=
   REACT_APP_PREVIEW_BR_BASE_URL=http://localhost:8080/site/_cmsinternal/spa-channel
   REACT_APP_PREVIEW_SPA_BASE_URL=/site/_cmsinternal/spa-channel?bloomreach-preview=true
   

   For Next.js applications:

   PUBLIC_URL=http://localhost:3000
   
   LIVE_BR_BASE_URL=http://localhost:8080/site/spa-channel
   LIVE_SPA_BASE_URL=
   PREVIEW_BR_BASE_URL=http://localhost:8080/site/_cmsinternal/spa-channel
   PREVIEW_SPA_BASE_URL=/site/_cmsinternal/spa-channel?bloomreach-preview=true
   

3. Update the URL Rewriter module configuration to match the requirements described in the URL Rewriter Rules documentation.

Code Changes

The @bloomreach/react-sdk library introduces a new API. Update your application code as shown in the following examples.

Application Component

Before:

import { CmsPage } from 'bloomreach-experience-react-sdk';

const cmsUrls = {
  preview: {
    hostname: '127.0.0.1',
    port: 9080,
    channelPath: 'spa-channel',
  },
  live: {
    hostname: 'localhost',
    port: 9080,
    channelPath: 'spa-channel',
  },
};

const componentDefinitions = {
  Banner: { component: Banner, wrapInContentComponent: true },
  Content: { component: Content, wrapInContentComponent: true },
};

const request = { hostname: window.location.hostname, path: window.location.pathname + window.location.search };

return <CmsPage componentDefinitions={componentDefinitions} cmsUrls={cmsUrls} request={request} createLink={createLink} />;
copy

After:

import { BrPage } from '@bloomreach/react-sdk';

const configuration = {
  httpClient: axios,
  options: {
    live: {
      cmsBaseUrl: process.env.REACT_APP_LIVE_BR_BASE_URL,
      spaBaseUrl: process.env.REACT_APP_LIVE_SPA_BASE_URL,
    },
    preview: {
      cmsBaseUrl: process.env.REACT_APP_PREVIEW_BR_BASE_URL,
      spaBaseUrl: process.env.REACT_APP_PREVIEW_SPA_BASE_URL,
    },
  },
  request: {
    path: `${window.location.pathname}${window.location.search}`,
  },
};

const mapping = { Banner, Content };

return <BrPage configuration={configuration} mapping={mapping} />;
copy

Inline Rendering

Before:

import { RenderCmsComponent } from 'bloomreach-experience-react-sdk';

<RenderCmsComponent path="menu" renderComponent={CmsMenu} />
copy

After:

import { BrComponent } from '@bloomreach/react-sdk';

<BrComponent path="menu">
  <Menu />
</BrComponent>
copy

Components Rendering

Before:

import { RenderCmsComponent } from 'bloomreach-experience-react-sdk';

<RenderCmsComponent />
copy

After:

import { BrComponent } from '@bloomreach/react-sdk';

<BrComponent />
copy

Component

Before:

const { content, manageContentButton, preview } = props;

return (
  <div className={`jumbotron ${preview ? 'has-edit-button' : ''}">
    { manageContentButton }
    { content.title && <h1>{content.title}</h1> }
  <div>
);
copy

After:

import { BrManageContentButton } from '@bloomreach/react-sdk';

const { document: documentRef } = props.component.getModels();
const document = documentRef && props.page.getContent(documentRef);

if (!document) {
  return null;
}

const { title } = document.getData();

return (
  <div className={`jumbotron ${props.page.isPreview() ? 'has-edit-button' : ''}`}>
    <BrManageContentButton content={document} />
    { title && <h1>{title}</h1> }
  </div>
);
copy

Menu Component

Before:

import { CmsEditButton, getNestedObject } from 'bloomreach-experience-react-sdk';

const { configuration, preview } = this.props;

if (!getNestedObject(configuration, ['models', 'menu', 'siteMenuItems', 0])) {
  return null;
}

const menuConfiguration = getNestedObject(configuration, ['models', 'menu']);

return (
  <ul className="navbar-nav">
    { preview ? <CmsEditButton configuration={menuConfiguration} preview={preview} /> : null }
  </ul>
);
copy

After:

import { BrManageMenuButton } from '@bloomreach/react-sdk';

const { menu } = props.component.getModels();

return (
  <ul className={`navbar-nav ${props.page.isPreview() ? 'has-edit-button' : ''}`}>
    <BrManageMenuButton menu={menu} />
  </ul>
);
copy

Menu Link

Before:

import { createLink } from 'bloomreach-experience-react-sdk';

return (
  <li className="nav-item">
    { createLink('self', configuration, 'Link Text', 'link-class') }
  </li>
);
copy

After:

return (
  <li className="nav-item">
    <a href={props.page.getUrl(item._links.site)} className="link-class">Link Text</a>
  </li>
);
copy

Resource Link

Before:

import { getImageUrl } from 'bloomreach-experience-react-sdk';

const { content, pageModel, preview } = props;
const image = getImageUrl(content.image, pageModel, preview);

return (
  <div>
    { image && <img src={image} alt={content.title} /> }
  </div>
);
copy

After:

const { document: documentRef } = props.component.getModels();
const document = documentRef && props.page.getContent(documentRef);

if (!document) {
  return null;
}

const { image: imageRef, title } = document.getData();
const image = imageRef && props.page.getContent(imageRef);

return (
  <div>
    { image && <img src={image.getUrl()} alt={title} /> }
  </div>
);
copy

Content Links

Before:

import { parseAndRewriteLinks } from 'bloomreach-experience-react-sdk';

const { content, preview } = props;

return (
  <div>
    { parseAndRewriteLinks(content.content.value, preview) }
  </div>
);
copy

After:

const { document: documentRef } = props.component.getModels();
const document = documentRef && props.page.getContent(documentRef);

if (!document) {
  return null;
}

const { content } = document.getData();

return <div dangerouslySetInnerHTML={{ __html: props.page.rewriteLinks(content.value) }} />;
copy

Date Parsing

Before:

import { parseDate } from 'bloomreach-experience-react-sdk';

const { content } = props;

return (
  <div>
    { parseDate(content.date) }
  </div>
);
copy

After:

const { document: documentRef } = props.component.getModels();
const document = documentRef && props.page.getContent(documentRef);

if (!document) {
  return null;
}

const { date } = document.getData<DocumentData>();

return (
  <div>
    { new Date(date).toDateString() }
  </div>
);
copy