From a4030c5e0453dda568a212f399dc629475085894 Mon Sep 17 00:00:00 2001 From: Colum Ferry Date: Sun, 20 Oct 2024 14:35:52 +0100 Subject: [PATCH] docs(website-new): add nx guides --- apps/website-new/docs/en/_meta.json | 4 + .../docs/en/guide/start/quick-start.mdx | 4 + .../en/practice/frameworks/angular/_meta.json | 1 + .../angular/using-nx-for-angular.mdx | 172 ++++++++++++++++++ .../en/practice/frameworks/react/_meta.json | 2 +- .../frameworks/react/using-nx-for-react.mdx | 172 ++++++++++++++++++ 6 files changed, 354 insertions(+), 1 deletion(-) create mode 100644 apps/website-new/docs/en/practice/frameworks/angular/using-nx-for-angular.mdx create mode 100644 apps/website-new/docs/en/practice/frameworks/react/using-nx-for-react.mdx diff --git a/apps/website-new/docs/en/_meta.json b/apps/website-new/docs/en/_meta.json index 8a0f00a3c5..eba64d2706 100644 --- a/apps/website-new/docs/en/_meta.json +++ b/apps/website-new/docs/en/_meta.json @@ -44,6 +44,10 @@ { "text": "Zephyr Cloud", "link": "https://zephyr-cloud.io/" + }, + { + "text": "Nx", + "link": "https://nx.dev/" } ] } diff --git a/apps/website-new/docs/en/guide/start/quick-start.mdx b/apps/website-new/docs/en/guide/start/quick-start.mdx index 2e90d38c77..729a3e3043 100644 --- a/apps/website-new/docs/en/guide/start/quick-start.mdx +++ b/apps/website-new/docs/en/guide/start/quick-start.mdx @@ -1,7 +1,11 @@ +import { Badge } from "@theme"; + # Quick Start Guide Before reading this guide, please first read the [Setting Up Environment](./setting-up-env). This guide will lead you step by step to learn how to use Module Federation. We will build two independent Single Page Applications (SPAs) that will share components using Module Federation. If you encounter unfamiliar terms in the following text, please refer to the [Glossary](./glossary). +_ You can also use [Nx](https://nx.dev) to rapidly scaffold Module Federation projects for [React](../../practice/frameworks/react/using-nx-for-react) and [Angular](../../practice/frameworks/angular/using-nx-for-angular)._ + ## Creating a Producer ### 1. Initializing the Project diff --git a/apps/website-new/docs/en/practice/frameworks/angular/_meta.json b/apps/website-new/docs/en/practice/frameworks/angular/_meta.json index 6264b4b24a..aeb52f448a 100644 --- a/apps/website-new/docs/en/practice/frameworks/angular/_meta.json +++ b/apps/website-new/docs/en/practice/frameworks/angular/_meta.json @@ -1,5 +1,6 @@ [ "angular-cli", + "using-nx-for-angular", "angular-mfe", "mf-ssr-angular", "service-workers-mf", diff --git a/apps/website-new/docs/en/practice/frameworks/angular/using-nx-for-angular.mdx b/apps/website-new/docs/en/practice/frameworks/angular/using-nx-for-angular.mdx new file mode 100644 index 0000000000..dba78494d6 --- /dev/null +++ b/apps/website-new/docs/en/practice/frameworks/angular/using-nx-for-angular.mdx @@ -0,0 +1,172 @@ +import { Steps, Badge } from '@theme'; + +# Using Nx CLI for Angular + +This guide explains how to integrate Module Federation for Angular projects using the [Nx CLI](https://nx.dev). + +## Installation + + To start, create a new Nx workspace ready for application development. + + ```bash + npx -y create-nx-workspace@latest myorg --preset=apps + cd myorg + ``` + + Next, we want to add the `@nx/angular` plugin to provide Angular capabilities to our Nx workspace. + + ```bash + npx nx add @nx/angular + ``` + +## Generate Shell (Host) with Remotes + +The Shell (Host) is crucial for Module Federation integration. Nx offers [generators](https://nx.dev/features/generate-code#generate-code) to simplify the process of setting up an application with Module Federation enabled. +These are the [`host`](https://nx.dev/nx-api/angular/generators/host) and [`remote`](https://nx.dev/nx-api/angular/generators/remote) generators. +The `host` generator actually allows you to specify a `--remotes` option, wherein you can generate remotes that you know you'll need all in one command. + +_ Nx currently uses `@module-federation/enhanced/webpack` to provide Module Federation capabilities using Webpack for Angular._ + + + ### Scaffold the Shell (Host) application + + Let's create a shell called `shop` in the `apps/` directory with remotes called `products`, `cart` and `checkout`. + + ```bash + npx nx g @nx/angular:host apps/shop --remotes=products,cart,checkout + ``` + + You'll notice four applications have been generated in the `apps/` directory. + At this point, everything is generated and configured correctly. + + _ Nx will configure the routing between the shell and the remote applications, as well as attaching each remote application to the shell in the `module-federation.config.ts` file to inform Module Federation of the remotes._ + + ### Serving your Module Federation setup + + Nx employs several techniques when working with Module Federation to ensure a great developer experience (DX), performance and scalability. + Once such technique involves only serving remotes that you're actively working with file watching attached. In Nx, these are called `dev remotes`. + The other projects are built by Nx and served statically via `http-server`. These are called `static remotes`. + + _ A bonus benefit of using Nx with Static Remotes comes from [Nx Caching](https://nx.dev/features/cache-task-results). Any remote that you have not changed, will be restored from cache and served, reducing compute overhead._ + + To serve your shell with all remotes treated as Static Remotes, run: + + ```bash + npx nx serve shop + ``` + + You'll now be able to access `shop` on `localhost:4200` and you can navigate between the remote applications using the links at the top of the page. + + When you're actively working on a remote application (a Dev Remote), you can pass the `--devRemotes` flag to inform Nx to use `webpack-dev-server` to serve the remote application, allowing for HMR and file watching. + + ```bash + npx nx serve shop --devRemotes=products + ``` + + Now, if you make changes to your `products` application, they will be reflected in the shell application in the browser. + + _ To learn more about why Nx recommends serving everything, read [here](https://nx.dev/concepts/module-federation/module-federation-and-nx#develop-as-a-user)._ + + ### Building your Module Federation setup + + Nx cares a lot about performance and DX, especially in monorepos. It offers you a command that will let you build everything at once. Helpful for full redeployments of all projects in the Module Federation system. + + ```bash + npx nx run-many -t build + ``` + + When running this command, if Nx detects a project did not change, it will restore the cached build artifact for that project instead of rebuilding it. However, sometimes this is still overkill. + Therefore, to only rebuild the projects that have actually been changed, and cut down any additional time spent restoring cached build artifacts, Nx offers a command to only recompute affected projects. + + ```bash + npx nx affected -t build + ``` + + You can view the build artifacts at `dist/apps`. + + + +## Adding Additional Remotes + +As we develop our application, we often need to add more remote applications. This is when Nx's `remote` generator becomes extremely useful. +Not only will it scaffold an Angular project with Module Federation configured, it also allows us to tell it which `host` application it belongs to and it will update the `host` to configure the new remote. + + + ### Scaffold new Remote application + + Let's add a new remote called `login` and attach it to our `shop` shell. + + ```bash + npx nx g @nx/angular:remote apps/login --host=shop + ``` + + It's that simple. If we run `npx nx serve shop --devRemotes`, we can now continue development on the `login` remote and see it reflected in the browser. + + +## Understanding Nx's Module Federation Abstractions + +Nx aims to make working with Module Federation as simplistic as possible while also providing a mechanism wherein the Nx team can ship optimizations, new features and fixes as seamlessly as possible. +To achieve this, it uses some abstractions over the underlying `ModuleFederationPlugin`. + +### Nx's ModuleFederationConfig + +Nx provides it's own `ModuleFederationConfig` interface which is a streamlined version of what is needed for the `ModuleFederationPlugin`. +You can view it in-depth [here](https://github.com/nrwl/nx/blob/master/packages/webpack/src/utils/module-federation/models/index.ts#L41). + +Let's focus on the most important aspects + + + #### Remotes + + The `remotes` option gives you two options for defining remote applications used by the shell (host). + + You can provide an array of Nx project names, or a tuple, defining the Nx project name, and the entry location for the remote. + + ```js + remotes: ["products", ["cart", "http://my-live-cart.myapp.com/mf-manifest.json"]] + ``` + + Under the hood, Nx will parse it's [Project Graph](https://nx.dev/features/explore-graph) to discover information around the entry location of the remote project and configure the `ModuleFederationPlugin` accordingly. + This is also used to serve the Module Federation setup when you run `npx nx serve shop`. + + #### Exposes + + The `exposes` option matches the exposes option in the `ModuleFederationPlugin` and provides you the ability to specify which modules should be federated by a remote application. + + #### Shared + + Nx will use its project graph to determine all the dependencies (npm and local) that are used by the projects in the Module Federation setup. It will then share all these dependencies at the detected version as singletons. This is great for getting up and running quickly, but sometimes, you need to control this behaviour. + The `shared` option allows you to pass a function where you can write custom logic to determine how a dependency should be shared. + + ```js + // do not share lodash to allow better tree-shaking + shared: function(libraryName, shareConfig) { + if(libraryName === 'lodash') { + return false + } + } + ``` + + +### Nx's withModuleFederation + +The `withModuleFederation` helper resides in the `webpack.config.ts` file. +It's primary purpose is to set up the `ModuleFederationPlugin` based on the `config` provided by `module-federation.config.ts` + +However, it also allows you to further configure other properties of `ModuleFederationConfig`. + +```js +withModuleFederation(config, { + dts: false, + runtimePlugins: [] +}); +``` + +## Learn More + +The links below are useful to learn more about Nx's support for Module Federation. + +- [Module Federation and Nx](https://nx.dev/concepts/module-federation/module-federation-and-nx) +- [Micro Frontend Architecture](https://nx.dev/concepts/module-federation/micro-frontend-architecture) +- [Nx Module Federation Technical Overview](https://nx.dev/concepts/module-federation/nx-module-federation-technical-overview) +- [Nx Module Federation Recipes](https://nx.dev/recipes/module-federation) diff --git a/apps/website-new/docs/en/practice/frameworks/react/_meta.json b/apps/website-new/docs/en/practice/frameworks/react/_meta.json index 768d1c3ce8..5c817e06ae 100644 --- a/apps/website-new/docs/en/practice/frameworks/react/_meta.json +++ b/apps/website-new/docs/en/practice/frameworks/react/_meta.json @@ -1 +1 @@ -["index", "i18n-react"] +["index", "using-nx-for-react", "i18n-react"] diff --git a/apps/website-new/docs/en/practice/frameworks/react/using-nx-for-react.mdx b/apps/website-new/docs/en/practice/frameworks/react/using-nx-for-react.mdx new file mode 100644 index 0000000000..dfbb367c0c --- /dev/null +++ b/apps/website-new/docs/en/practice/frameworks/react/using-nx-for-react.mdx @@ -0,0 +1,172 @@ +import { Steps, Badge } from '@theme'; + +# Using Nx CLI for React + +This guide explains how to integrate Module Federation for React projects using the [Nx CLI](https://nx.dev). + +## Installation + + To start, create a new Nx workspace ready for application development. + + ```bash + npx -y create-nx-workspace@latest myorg --preset=apps + cd myorg + ``` + + Next, we want to add the `@nx/react` plugin to provide React capabilities to our Nx workspace. + + ```bash + npx nx add @nx/react + ``` + +## Generate Shell (Host) with Remotes + +The Shell (Host) is crucial for Module Federation integration. Nx offers [generators](https://nx.dev/features/generate-code#generate-code) to simplify the process of setting up an application with Module Federation enabled. +These are the [`host`](https://nx.dev/nx-api/react/generators/host) and [`remote`](https://nx.dev/nx-api/react/generators/remote) generators. +The `host` generator actually allows you to specify a `--remotes` option, wherein you can generate remotes that you know you'll need all in one command. + +_ Nx currently uses `@module-federation/enhanced/rspack` to provide Module Federation capabilities using Rspack for React._ + + + ### Scaffold the Shell (Host) application + + Let's create a shell called `shop` in the `apps/` directory with remotes called `products`, `cart` and `checkout`. + + ```bash + npx nx g @nx/react:host apps/shop --remotes=products,cart,checkout + ``` + + You'll notice four applications have been generated in the `apps/` directory. + At this point, everything is generated and configured correctly. + + _ Nx will configure the routing between the shell and the remote applications, as well as attaching each remote application to the shell in the `module-federation.config.ts` file to inform Module Federation of the remotes._ + + ### Serving your Module Federation setup + + Nx employs several techniques when working with Module Federation to ensure a great developer experience (DX), performance and scalability. + Once such technique involves only serving remotes that you're actively working with file watching attached. In Nx, these are called `dev remotes`. + The other projects are built by Nx and served statically via `http-server`. These are called `static remotes`. + + _ A bonus benefit of using Nx with Static Remotes comes from [Nx Caching](https://nx.dev/features/cache-task-results). Any remote that you have not changed, will be restored from cache and served, reducing compute overhead._ + + To serve your shell with all remotes treated as Static Remotes, run: + + ```bash + npx nx serve shop + ``` + + You'll now be able to access `shop` on `localhost:4200` and you can navigate between the remote applications using the links at the top of the page. + + When you're actively working on a remote application (a Dev Remote), you can pass the `--devRemotes` flag to inform Nx to use `@rspack/dev-server` to serve the remote application, allowing for HMR and file watching. + + ```bash + npx nx serve shop --devRemotes=products + ``` + + Now, if you make changes to your `products` application, they will be reflected in the shell application in the browser. + + _ To learn more about why Nx recommends serving everything, read [here](https://nx.dev/concepts/module-federation/module-federation-and-nx#develop-as-a-user)._ + + ### Building your Module Federation setup + + Nx cares a lot about performance and DX, especially in monorepos. It offers you a command that will let you build everything at once. Helpful for full redeployments of all projects in the Module Federation system. + + ```bash + npx nx run-many -t build + ``` + + When running this command, if Nx detects a project did not change, it will restore the cached build artifact for that project instead of rebuilding it. However, sometimes this is still overkill. + Therefore, to only rebuild the projects that have actually been changed, and cut down any additional time spent restoring cached build artifacts, Nx offers a command to only recompute affected projects. + + ```bash + npx nx affected -t build + ``` + + You can view the build artifacts at `dist/apps`. + + + +## Adding Additional Remotes + +As we develop our application, we often need to add more remote applications. This is when Nx's `remote` generator becomes extremely useful. +Not only will it scaffold an Angular project with Module Federation configured, it also allows us to tell it which `host` application it belongs to and it will update the `host` to configure the new remote. + + + ### Scaffold new Remote application + + Let's add a new remote called `login` and attach it to our `shop` shell. + + ```bash + npx nx g @nx/react:remote apps/login --host=shop + ``` + + It's that simple. If we run `npx nx serve shop --devRemotes`, we can now continue development on the `login` remote and see it reflected in the browser. + + +## Understanding Nx's Module Federation Abstractions + +Nx aims to make working with Module Federation as simplistic as possible while also providing a mechanism wherein the Nx team can ship optimizations, new features and fixes as seamlessly as possible. +To achieve this, it uses some abstractions over the underlying `ModuleFederationPlugin`. + +### Nx's ModuleFederationConfig + +Nx provides it's own `ModuleFederationConfig` interface which is a streamlined version of what is needed for the `ModuleFederationPlugin`. +You can view it in-depth [here](https://github.com/nrwl/nx/blob/master/packages/webpack/src/utils/module-federation/models/index.ts#L41). + +Let's focus on the most important aspects + + + #### Remotes + + The `remotes` option gives you two options for defining remote applications used by the shell (host). + + You can provide an array of Nx project names, or a tuple, defining the Nx project name, and the entry location for the remote. + + ```js + remotes: ["products", ["cart", "http://my-live-cart.myapp.com/mf-manifest.json"]] + ``` + + Under the hood, Nx will parse it's [Project Graph](https://nx.dev/features/explore-graph) to discover information around the entry location of the remote project and configure the `ModuleFederationPlugin` accordingly. + This is also used to serve the Module Federation setup when you run `npx nx serve shop`. + + #### Exposes + + The `exposes` option matches the exposes option in the `ModuleFederationPlugin` and provides you the ability to specify which modules should be federated by a remote application. + + #### Shared + + Nx will use its project graph to determine all the dependencies (npm and local) that are used by the projects in the Module Federation setup. It will then share all these dependencies at the detected version as singletons. This is great for getting up and running quickly, but sometimes, you need to control this behaviour. + The `shared` option allows you to pass a function where you can write custom logic to determine how a dependency should be shared. + + ```js + // do not share lodash to allow better tree-shaking + shared: function(libraryName, shareConfig) { + if(libraryName === 'lodash') { + return false + } + } + ``` + + +### Nx's withModuleFederation + +The `withModuleFederation` helper resides in the `rspack.config.ts` file. +It's primary purpose is to set up the `ModuleFederationPlugin` based on the `config` provided by `module-federation.config.ts` + +However, it also allows you to further configure other properties of `ModuleFederationConfig`. + +```js +withModuleFederation(config, { + dts: false, + runtimePlugins: [] +}); +``` + +## Learn More + +The links below are useful to learn more about Nx's support for Module Federation. + +- [Module Federation and Nx](https://nx.dev/concepts/module-federation/module-federation-and-nx) +- [Micro Frontend Architecture](https://nx.dev/concepts/module-federation/micro-frontend-architecture) +- [Nx Module Federation Technical Overview](https://nx.dev/concepts/module-federation/nx-module-federation-technical-overview) +- [Nx Module Federation Recipes](https://nx.dev/recipes/module-federation)