From 27658c7cb773fca1faad235ae81f8056f1485a97 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Tue, 31 May 2022 08:52:41 -0700 Subject: [PATCH] ENDOC-504 Apply to Next --- .../tutorials/create/mfe/communication.md | 2 +- .../docs/next/tutorials/create/mfe/react.md | 291 +++++------------- 2 files changed, 81 insertions(+), 212 deletions(-) diff --git a/vuepress/docs/next/tutorials/create/mfe/communication.md b/vuepress/docs/next/tutorials/create/mfe/communication.md index 79a157c381..e224039538 100644 --- a/vuepress/docs/next/tutorials/create/mfe/communication.md +++ b/vuepress/docs/next/tutorials/create/mfe/communication.md @@ -275,7 +275,7 @@ You’ve now created a micro frontend that listens to custom events. Now let's add the publisher and subscriber micro frontends in Entando. -> Note: These follow the same steps as in the [Create a React Micro Frontend](./react.md#build-it) tutorial. +> Note: These follow the same steps as in the [Create a React Micro Frontend](./react.md#build-the-react-app) tutorial. ### Create Environment File diff --git a/vuepress/docs/next/tutorials/create/mfe/react.md b/vuepress/docs/next/tutorials/create/mfe/react.md index c3d8a9dac3..506956859c 100644 --- a/vuepress/docs/next/tutorials/create/mfe/react.md +++ b/vuepress/docs/next/tutorials/create/mfe/react.md @@ -4,65 +4,58 @@ sidebarDepth: 2 # Create a React Micro Frontend - - ## Prerequisites -- [A working instance of Entando.](../../../docs/getting-started/) -- Use the Entando CLI to verify all dependencies are installed with the command `ent check-env develop`. +- [A working instance of Entando](../../../docs/getting-started/) +- Use the [Entando CLI](../../../docs/reference/entando-cli.md) to verify all dependencies are installed: +``` +ent check-env develop +``` -## Create React App -We'll use [Create React App](https://create-react-app.dev/) to generate a simple app in seconds. -1. Create 'my-widget' directory structure with the following: +## Create a React App +[Create React App](https://create-react-app.dev/) allows you to generate a simple app in seconds. +1. Create a React app: ``` bash npx create-react-app my-widget --use-npm ``` - -This is the expected output: +This tutorial updates the following files: my-widget ├── README.md - ├── node_modules - ├── package.json - ├── .gitignore ├── public - │ ├── favicon.ico - │ ├── index.html - │ ├── logo192.png - │ ├── logo512.png - │ ├── manifest.json - │ └── robots.txt + │ └── index.html └── src - ├── App.css ├── App.js - ├── App.test.js - ├── index.css - ├── index.js - ├── logo.svg - ├── serviceWorker.js - └── setupTests.js + └── index.js -2. Start the app +2. Start the app: ``` bash cd my-widget npm start ``` -### Wrap with Custom Element +The React app should open in your browser at `http://localhost:3000`. + +### Configure the Custom Element -1. Add a new file `src/WidgetElement.js` with the following custom element to wrap the entire React app +The steps below wrap the app component with an HTML custom element. The `connectedCallback` method renders the React app when the custom element is added to the DOM. + +1. In `my-widget/src`, create a file named `WidgetElement.js` + +2. Add the following code to `WidgetElement.js`: ``` js import React from 'react'; -import ReactDOM from 'react-dom'; +import ReactDOM from 'react-dom/client'; import App from './App'; class WidgetElement extends HTMLElement { connectedCallback() { this.mountPoint = document.createElement('div'); this.appendChild(this.mountPoint); - ReactDOM.render(, this.mountPoint); + const root = ReactDOM.createRoot(this.mountPoint); + root.render(); } } @@ -70,234 +63,106 @@ customElements.define('my-widget', WidgetElement); export default WidgetElement; ``` -The React `root` node is programatically generated in the `connectedCallback` method when the custom element is added to the DOM. -::: tip -`connectedCallback` is a lifecycle hook that [runs each time the element is added to the DOM.](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#Using_the_lifecycle_callbacks) +::: tip Custom Element Names +- [Must contain a hyphen `-` in the name](https://stackoverflow.com/questions/22545621/do-custom-elements-require-a-dash-in-their-name) +- Cannot be a single word +- Should follow `kebab-case` naming convention ::: -::: tip Custom Elements -- [Must contain a hyphen `-` in the name.](https://stackoverflow.com/questions/22545621/do-custom-elements-require-a-dash-in-their-name) -- Cannot be a single word. -- Should follow `kebab-case` for naming convention. -::: +### Display the Custom Element -### Import Custom Element - -1. Open `src/index.js`. The initial file looks like: - -``` js -import React from 'react'; -import ReactDOM from 'react-dom'; -import './index.css'; -import App from './App'; -import * as serviceWorker from './serviceWorker'; - -ReactDOM.render(, 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(); -``` - -2. Replace the entire file with these two lines +1. Replace the entire contents of `src/index.js` with these two lines: ``` js import './index.css'; import './WidgetElement'; ``` -### Test Micro Frontend - -1. Open `public/index.html` - -2. Replace `
` with the custom element `` +2. In `public/index.html`, replace `
` with this: ``` html - - - ... - ``` -::: tip Congratulations! -You’re now running `React` in a containerized micro frontend. -::: - -## Build the Resource URL - -Add your micro frontend to Entando by uploading the JavaScript and CSS files to the `public` folder. This is the way Entando makes files available to the public. - -### Add Widget - -First, add a widget to get the resource URL for the `public` folder. Then use the same widget to add the Micro Frontend to Entando. - -1. Go to `Components > Micro frontends & Widgets` in the App Builder - -2. Click `Add` in the lower right corner - -![New widget screen](./img/new-widget-screen.png) +3. Observe your browser automatically redisplay the React app -3. Enter the following: -- `Title: My Widget` → enter both English and Italian languages -- `Code: my_widget` → dashes are not allowed -- `Group: Free Access` -- `Icon`: → upload an icon of your choice -- In the center panel under `Custom UI`, enter the following: - -``` ftl -<#assign wp=JspTaglibs[ "/aps-core"]> -<@wp.resourceURL /> -``` -4. Click `Save` - -::: tip -`<#assign wp=JspTaglibs[ "/aps-core"]>` gives you access to the `@wp` object where you can use environment variables like `resourceURL`. +::: tip Congratulations! +You’re now using a custom element to display a React app. ::: +## Display the Micro Frontend in Entando +### Build the React App -### Add Page - -Next, add the widget to a page to view the `Resource URL`. -If you're getting started with a new install of Entando, add the widget to the `Home` page. - ---- +To deploy the custom element into Entando as a micro frontend, you must perform a production build of the React app. -> For Experienced Entando users: Add a new page → Add your widget to the page - ---- - -1. Go to `Pages` → `Management` - -2. Next to the `Home` folder, under `Actions`, → `Edit` - -3. In the `Title` field, choose `My Widget` - -4. In the Code field, choose `my_widget` - -5. Under Page groups, in the Owner group field, choose `Free Access` - -4. Scroll down to `Page Template` and select `Single Frame Page`. Leave all other fields blank or in the default setting. - -5. Click `Save and Design`. You are now in the page Designer. - -6. In the Search field of the right sidebar, type `My Widget`. It will show as an option. - -7. Drag and drop `My Widget` into the `Sample Frame` in the body of the page - -8. Click `Publish` - -9. In the top right corner, click `View Published Page`. This will take you to a blank home page with your widget. - -10. Copy the `Resource URL` at the top. For example, this is the URL in a quickstart environment set up via the Getting Started guide: - -``` -/entando-de-app/cmsresources/ -``` - -### Build It - -With the Resource URL where the new React App will be hosted, you are ready to build. - -1. Create an `.env.production` file in the root of `my-widget` project - -2. Add the `PUBLIC_URL` into the file. - -``` +1. In the `my-widget` directory, create an `.env.production` file that consists of one line: +``` text PUBLIC_URL=/entando-de-app/cmsresources/my-widget ``` + ::: warning Notes -- `/entando-de-app/cmsresources/` is the Resource URL for your Entando application -- `/my-widget` is the public folder that's created to host the files. +- `/entando-de-app/cmsresources/` is the Resource URL for your Entando Application, which matches nearly all development environments. Consult your Entando admin or use the following fragment to discover the Resource URL. +``` ftl + <#assign wp=JspTaglibs[ "/aps-core"]> + <@wp.resourceURL /> +``` +- `/my-widget` is the public folder that hosts the JavaScript and CSS files for the React app ::: -### npm build - -1. Open a command line and navigate to the project root of your `my-widget` - -2. Run the command: +2. Build the app: ``` bash npm run build ``` -3. Rename the following files generated 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 - -::: warning Generated Build Files -The JavaScript and CSS files are renamed so App Builder can deploy the new versions of the micro frontend without having to update the `Custom UI` field of the widget. -::: - -If you want to use the original [file names with the content hashes to avoid potential caching issues in your browser](https://create-react-app.dev/docs/using-the-public-folder/#adding-assets-outside-of-the-module-system), 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. - -::: warning 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 you are ready to host the micro frontend in Entando. - -### Create Public Folder - -1. Navigate to `Entando App Builder` in your browser - -2. Click `Administration` at the lower left hand side of the screen - -3. Click the `File browser` tab +### Upload the React files -4. Choose the `public` folder +To set up the micro frontend to use in Entando: -5. Click `Create folder` +1. In your App Builder, go to `Administration` → `File browser` → `public` -6. Enter `my-widget` +2. Click `Create folder` and name it "my-widget" to match the `.env.production` path above -7. Click `Save` +3. Click `Save` -8. Click `my-widget` +4. Click `my-widget` -9. Create the same folder structure as your generated build directory +5. Create a folder structure similar to your generated build directory: - `my-widget/static/css` - `my-widget/static/js` - `my-widget/static/media` -10. Upload the renamed files in the corresponding `js` and `css` folders +6. Upload the css, js, and logo files from the corresponding directories under `my-widget/build/static`, for example: -- `my-widget/static/css/main.css` -- `my-widget/static/js/main.js` -- `my-widget/static/js/runtime.js` -- `my-widget/static/js/vendor.js` +- `my-widget/build/static/css/main.073c9b0a.css` +- `my-widget/build/static/js/main.b9eb8fa4.js` +- `my-widget/build/static/media/logo.6ce2458023.svg` -Note: You can drag and drop the files in your browser +> Note: The generated ID of each file name (e.g. '073c9b0a') may change after every build. These folders may also contain LICENSE.txt or .map files, but they are not applicable to this tutorial. +### Create the Widget -11. Upload the `React` logo +Add a widget for your MFE. -- `my-widget/static/media/logo.5d5d9eef.svg` → You don't need to rename this file +1. In your App Builder, go to `Components` → `MFE & Widgets` -### Update Custom UI Field - -1. Go to `Components` → `Micro frontends & Widgets` +2. Click `Add` in the lower right corner -2. Under the `My Widgets` category → next to `My Widget` → under `Action` → select `Edit` +![New widget screen](./img/new-widget-screen.png) -3. Update `Custom UI` field: +3. Edit the fields below: +- `Title`: "My Widget" → enter this in both the English and Italian language fields +- `Code`: "my_widget" → dashes are not allowed +- `Group`: "Free Access" +- `Icon`: upload or select an icon of your choice +- In the center panel under `Custom UI`, enter the following. Make sure to use the actual file names from your build. ``` ftl <#assign wp=JspTaglibs[ "/aps-core"]> - - - - + + ``` @@ -305,15 +170,19 @@ Note: You can drag and drop the files in your browser ### View the Widget -View the React micro frontend in action on your page. +Place the React micro frontend onto a page to see it in action. + +1. In the `Entando App Builder`, go to `Pages` → `Management` + +2. Choose an existing page (or [create a new one](../../compose/page-management.md#create-a-page)) and select `Design` from its Actions -1. In the `Entando App Builder` go back to `Pages` → `Management` +3. Find your widget in the `Widgets` sidebar and drag it onto the page -2. Next to the page you created, under `Actions`→ `Design`. This takes you back to the page Designer. +4. Click `Publish` -3. Click on `View Published Page` on the top right side +3. Click on `View Published Page` -![React Micro Frontend](./img/react-micro-frontend.png) + ::: tip Congratulations! You now have a React micro frontend running in Entando.