diff --git a/vuepress/docs/next/tutorials/create/mfe/communication.md b/vuepress/docs/next/tutorials/create/mfe/communication.md index e224039538..1106777648 100644 --- a/vuepress/docs/next/tutorials/create/mfe/communication.md +++ b/vuepress/docs/next/tutorials/create/mfe/communication.md @@ -275,8 +275,6 @@ 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-the-react-app) tutorial. - ### Create Environment File #### Publisher Widget diff --git a/vuepress/docs/next/tutorials/create/mfe/react.md b/vuepress/docs/next/tutorials/create/mfe/react.md index a47c39d4fc..226236f4f0 100644 --- a/vuepress/docs/next/tutorials/create/mfe/react.md +++ b/vuepress/docs/next/tutorials/create/mfe/react.md @@ -1,169 +1,123 @@ ---- -sidebarDepth: 2 ---- - # Create a React Micro Frontend ## Prerequisites - [A working instance of Entando](../../../docs/getting-started/) -- Use the [Entando CLI](../../../docs/getting-started/entando-cli.md) to verify all dependencies are installed: -``` -ent check-env develop -``` +- Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` + +## Create a React App in an Entando Bundle -## Create a React App -[Create React App](https://create-react-app.dev/) allows you to generate a simple app in seconds. +### Create the Bundle Project -1. Create a React app: -``` bash -npx create-react-app my-widget --use-npm -``` -This tutorial updates the following files: +1. Initialize a new bundle project by scaffolding the default files and folders: + ``` sh + ent bundle init simple-bundle + ``` - my-widget - ├── README.md - ├── public - │ └── index.html - └── src - ├── App.js - └── index.js +2. Add an MFE to the bundle project structure: + ``` sh + ent bundle mfe add simple-mfe + ``` +### Create a Simple React App +[Create React App](https://create-react-app.dev/) allows you to generate a simple app in seconds. -2. Start the app: -``` bash -cd my-widget -npm start -``` +1. From the bundle root folder, create a React app in `/simple-bundle/microfrontends/`: + ``` bash + npx create-react-app simple-mfe --use-npm + ``` + Use the bundle name you chose when adding an MFE to overwrite the empty bundle folder created in the previous step. -The React app should open in your browser at `http://localhost:3000`. +2. From the MFE folder, start the app: + ``` bash + cd microfrontends/simple-mfe + npm start + ``` + The React app should open in your browser at `http://localhost:3000`. ### Configure the Custom Element 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` +1. In `simple-mfe/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/client'; + import App from './App'; -``` js -import React from 'react'; -import ReactDOM from 'react-dom/client'; -import App from './App'; - -class WidgetElement extends HTMLElement { - connectedCallback() { - this.mountPoint = document.createElement('div'); - this.appendChild(this.mountPoint); - const root = ReactDOM.createRoot(this.mountPoint); - root.render(); - } -} - -customElements.define('my-widget', WidgetElement); - -export default WidgetElement; -``` - -::: 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 -::: - -### Display the Custom Element - -1. Replace the entire contents of `src/index.js` with these two lines: + class WidgetElement extends HTMLElement { + connectedCallback() { + this.mountPoint = document.createElement('div'); + this.appendChild(this.mountPoint); + const root = ReactDOM.createRoot(this.mountPoint); + root.render(); + } + } -``` js -import './index.css'; -import './WidgetElement'; -``` + customElements.define('simple-mfe', WidgetElement); -2. In `public/index.html`, replace `
` with this: + export default WidgetElement; + ``` -``` html - -``` + ::: tip Custom Element Names -3. Observe your browser automatically redisplay the React app + - [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 Congratulations! -You’re now using a custom element to display a React app. -::: - -## Display the Micro Frontend in Entando +### Display the Custom Element -### Build the React App +1. Replace the entire contents of `src/index.js` with these two lines: + ``` js + import './index.css'; + import './WidgetElement'; + ``` -To deploy the custom element into Entando as a micro frontend, you must perform a production build of the React app. +2. In `public/index.html`, replace `
` with the following: + ``` html + + ``` -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 -``` +3. Observe your browser automatically redisplay the React app. -::: warning Notes -- `/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 +::: tip Congratulations! +You’re now using a custom element to display a React app. ::: +## Display the React MFE in Entando -2. Build the app: -``` bash -npm run build -``` - -### Upload the React files -To set up the micro frontend to use in Entando: - -1. In your App Builder, go to `Administration` → `File browser` → `public` - -2. Click `Create folder` and name it "my-widget" to match the `.env.production` path above - -3. Click `Save` +1. From the root bundle directory, generate the Docker image: + ``` sh + ent bundle pack + ``` + This builds the widget and constructs a Docker image for the bundle. -4. Click `my-widget` +2. Publish the Docker image to a Docker registry: + ``` sh + ent bundle publish + ``` -5. Create a folder structure similar to your generated build directory: +3. Deploy the bundle to your Entando Application: + ``` sh + ent bundle deploy + ``` + Your bundle will appear in the Local Hub of your Entando instance, accessible from `App Builder` → `Hub`, and show a status of DEPLOYED. -- `my-widget/static/css` -- `my-widget/static/js` -- `my-widget/static/media` +4. Install the bundle in your Entando Application from `App Builder` → `Hub` or with the following command: + ``` sh + ent bundle install + ``` + Your bundle will now show a status of INSTALLED. -6. Upload the css, js, and logo files from the corresponding directories under `my-widget/build/static`, for example: - -- `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: 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 - -Add a widget for your MFE. +### Edit the Widget 1. In your App Builder, go to `Components` → `MFE & Widgets` -2. Click `Add` in the lower right corner +2. Scroll down to the "User" section and click on "simple-mfe" -![New widget screen](./img/new-widget-screen.png) - -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"]> - - - -``` +3. Edit the "Title" fields as desired and upload or select an icon of your choice 4. Click `Save` @@ -179,9 +133,7 @@ Place the React micro frontend onto a page to see it in action. 4. Click `Publish` -3. Click on `View Published Page` - - +5. Click on `View Published Page` ::: tip Congratulations! You now have a React micro frontend running in Entando. diff --git a/vuepress/docs/next/tutorials/create/mfe/widget-configuration.md b/vuepress/docs/next/tutorials/create/mfe/widget-configuration.md index fb0209a0c9..23c5dd61a3 100644 --- a/vuepress/docs/next/tutorials/create/mfe/widget-configuration.md +++ b/vuepress/docs/next/tutorials/create/mfe/widget-configuration.md @@ -98,7 +98,7 @@ npm start npm run build ``` -6. Load the updated `my-widget` files into Entando as was done for the [React MFE tutorial](./react.md#upload-the-react-files) +6. Load the updated `my-widget` files into Entando per the [React MFE tutorial](../mfe/react.md#display-the-react-mfe-in-entando) > Note: If you followed the React MFE tutorial, only `js/main.GENERATED-ID.js` needs to be added or updated. ## Step 2: Create a config MFE diff --git a/vuepress/docs/next/tutorials/create/ms/add-access-controls.md b/vuepress/docs/next/tutorials/create/ms/add-access-controls.md index 1ddf5253ae..6154474a88 100644 --- a/vuepress/docs/next/tutorials/create/ms/add-access-controls.md +++ b/vuepress/docs/next/tutorials/create/ms/add-access-controls.md @@ -64,7 +64,7 @@ private String clientId; ``` ### Step 2: Run your project in a local developer environment -The following commands must be run from your project directory. They leverage the [ent CLI](../../../docs/reference/entando-cli.md). +The following commands must be run from your project directory. They leverage the [ent CLI](../../../docs/getting-started/entando-cli.md). > Note: Refer to the [Run Blueprint-generated Microservices and Micro Frontends in Dev Mode tutorial](./run-local.md) for details.