# Create a React Micro Frontend

Tested Versions

node v13.8.0 → We suggest using nvm (opens new window) to handle node installations.

# Create React App

We'll use Create React App (opens new window) to create a simple app in seconds.

npx create-react-app my-widget --use-npm

This is the expected output:

my-widget
├── README.md
├── node_modules
├── package.json
├── .gitignore
├── public
│   ├── favicon.ico
│   ├── index.html
│   ├── logo192.png
│   ├── logo512.png
│   ├── manifest.json
│   └── robots.txt
└── src
    ├── App.css
    ├── App.js
    ├── App.test.js
    ├── index.css
    ├── index.js
    ├── logo.svg
    ├── serviceWorker.js
    └── setupTests.js

Start the app.

cd my-widget
npm start

# Wrap with Custom Element

Add a new file src/WidgetElement.js with the custom element that will wrap the entire React app.

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

class WidgetElement extends HTMLElement {
    connectedCallback() {
        this.mountPoint = document.createElement('div');
        this.appendChild(this.mountPoint);
        ReactDOM.render(<App />, this.mountPoint);
    }
}

customElements.define('my-widget', WidgetElement);

export default WidgetElement;

TIP

connectedCallback is a lifecycle hook that runs each time the element is added to the DOM. (opens new window)

The React root node is programatically generated in the connectedCallback method when our custom element is added to the DOM.

Custom Elements

# Import Custom Element

Open src/index.js. Here's what the initial file looks like:

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import * as serviceWorker from './serviceWorker';

ReactDOM.render(<App />, document.getElementById('root'));

// If you want your app to work offline and load faster, you can change
// unregister() to register() below. Note this comes with some pitfalls.
// Learn more about service workers: https://bit.ly/CRA-PWA
serviceWorker.unregister();

Replace the entire file with these two lines.

import './index.css';
import './WidgetElement';

# Test Micro Frontend

  1. Open public/index.html.

  2. Replace <div id="root"></div> with the custom element <my-widget />.

  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <my-widget />
    ...
  </body>

Congratulations!

You’re now running React in a containerized micro frontend.

# Get Resource URL

Let's add our micro frontend to Entando by adding our JavaScript and CSS files to the public folder.

TIP

Entando makes files publicly available through the public folder.

# Add Widget

Initially, we'll add a widget to get the resource URL for the public folder. Later on, we'll use the same widget to add our micro frontend to Entando.

  1. Go to Entando App Builder in your browser.

  2. Click UX PatternsWidgets at the top nav.

  3. Click Add at the upper right.

  4. Enter the following:

New widget screen

  • Title: My Widget → for both English and Italian languages
  • Code: my_widget → note: dashes are not allowed
  • Group: Free Access
  • Custom UI:
<#assign wp=JspTaglibs[ "/aps-core"]>
<@wp.resourceURL />

TIP

<#assign wp=JspTaglibs[ "/aps-core"]> gives you access to the @wp object where you can use environment variables like resourceURL.

  1. Click Save.

# Add Page

Next, let's add our widget to a page so we can view the Resource URL.

If you're getting started with a new install of Entando, let's add our widget to the Home page:


For Experienced Entando users:

Add a new page → Add your widget to the page


  1. Click Page DesignerPage Tree at the top nav.

  2. Next to the Home folder, under Actions, click Edit.

  3. Next to Page Template select Service Page.

  4. Click Save and Configure.

  5. In the Search field in right-hand sidebar, enter My Widget.

  6. Drag and drop My Widget into the Sample Frame in the main body of the page.

  7. Click Publish.

  8. At the upper right, click Go to Homepage.

  • This will take you to a blank home page with your widget.
  1. Copy the Resource URL.
/entando-de-app/cmsresources/

# Build It

Now that we have the resource URL where we'll host our Create React App, we're ready to build.

  1. Create an .env file in the project root of your Create React App.

  2. Add the PUBLIC_URL where we'll be hosting our files.

Example:

PUBLIC_URL=http://quickstart-entando.192.168.64.34.nip.io/entando-de-app/cmsresources/my-widget
  1. Replace quickstart-entando.192.168.64.34.nip.io/app-builder with the URL for your Entando App Builder instance. → How to find your Entando App Builder URL.

Notes

  • quickstart-entando.192.168.64.34.nip.io represents your Entando App Builder instance.
  • /entando-de-app/cmsresources/ is your Resource URL
  • my-widget is the public folder we'll create to host our files

# npm build

  1. Open a command line, and navigate to the project root of your Create React App.

  2. Run the command:

npm run build
  1. Rename the following generated files in the build directory.
Example of Generated Build File Rename to Function
build/static/js/2.f14073bd.chunk.js static/js/vendor.js Third-party libraries
build/static/js/runtime-main.8a835b7b.js static/js/runtime.js Bootstrapping logic
build/static/js/main.4a514a6d.chunk.js static/js/main.js App
build/static/css/main.5f361e03.chunk.css static/css/main.css Stylesheet

Generated Build Files

We rename the JavaScript and CSS files so we can deploy new versions of the micro frontend without having to update the Custom UI field of our widget to reference the new files.

If you want to use the original file names with the content hashes to avoid potential caching issues in your browser (opens new window), update the Custom UI field of your widget when deploying new versions of your micro frontend. The Custom UI settings will be covered in the next section.

Additional Deployment Options

  1. Install the micro frontend from a bundle in the Entando Component Repository.
  2. Add the micro frontend to Entando App Builder.
  3. Load the micro frontend from an API.

# Host Micro Frontend

Now we're ready to host our micro frontend in Entando.

# Create Public Folder

  1. Navigate to Entando App Builder in your browser.

  2. Click Configuration at the upper right hand side of the screen.

  3. Click the File Browser tab.

  4. Click the public folder.

  5. Click Create Folder.

  6. Enter my-widget.

  7. Click Save.

  8. Click publicmy-widget.

  9. Create the same folder structure as your generated build directory

  • my-widget/static/css
  • my-widget/static/js
  1. Upload the files we renamed in the corresponding js and css folders.
  • my-widget/static/css/main.css
  • my-widget/static/js/main.js
  • my-widget/static/js/runtime.js
  • my-widget/static/js/vendor.js

Note: You can drag and drop the files in your browser.

  1. Upload the React logo.
  • my-widget/static/media/logo.5d5d9eef.svg → You don't need to rename this file.

# Update Custom UI Field

  1. Click UX PatternsWidgets.

  2. Under the My Widgets cateogory → next to My Widget → under Action → select Edit.

  3. Update Custom UI field:

<#assign wp=JspTaglibs[ "/aps-core"]>
<link rel="stylesheet" type="text/css" href="<@wp.resourceURL />my-widget/static/css/main.css">
<script async src="<@wp.resourceURL />my-widget/static/js/runtime.js"></script>
<script async src="<@wp.resourceURL />my-widget/static/js/vendor.js"></script>
<script async src="<@wp.resourceURL />my-widget/static/js/main.js"></script>
<my-widget />
  1. Click Save.

# View in Homepage

Let's see the React micro frontend in action on our page.

  1. In the Entando App Builder dashboard, click Go to Homepage at the upper right.

  2. Go to the page that you created, and click refresh.

React Micro Frontend

Congratulations!

You now have a React micro frontend running in Entando.