Migrating an Angular CLI project to Nx
Within an Nx workspace, you gain many capabilities that help you build applications and libraries. If you are currently using an Angular CLI workspace, you can transform it into an Nx workspace.
Migrating to a Standalone Angular App with Nx
You can migrate to a Standalone Angular App with the command:
โฏ
npx nx@latest init
This command will install the correct version of Nx based on your Angular version.
This will enable you to use the Nx CLI in your existing Angular CLI workspace while keeping your existing file structure in place. The following changes will be made in your repo to enable Nx:
- The
nx
,@nx/workspace
andprettier
packages will be installed. - An
nx.json
file will be created in the root of your workspace. - For an Angular 14+ repo, the
angular.json
file is split into separateproject.json
files for each project.
Note: The changes will be slightly different for Angular 13 and lower.
Migrating to an Integrated Nx Monorepo
If you want to migrate your Angular CLI project to an Integrated Nx Monorepo, run the following command:
โฏ
npx nx@latest init --integrated
The command applies the following changes to your workspace:
- Installs the
nx
,@nx/angular
and@nx/workspace
packages. - Moves your applications into the
apps
folder, and updates the relevant file paths in your configuration files. - Moves your e2e suites into the
apps/<app name>-e2e
folder, and updates the relevant file paths in your configuration files. - Moves your libraries into the
libs
folder, and updates the relevant file paths in your configuration files. - Updates your
package.json
scripts to usenx
instead ofng
. - Splits your
angular.json
intoproject.json
files for each project with updated paths.
After the changes are applied, your workspace file structure should look similar to the one below:
1<workspace name>/
2โโโ apps/
3โ โโ <app name>/
4โ โโโ src/
5โ โ โโโ app/
6โ โ โโโ assets/
7โ โ โโโ favicon.ico
8โ โ โโโ index.html
9โ โ โโโ main.ts
10โ โ โโโ styles.css
11โ โโโ project.json
12โ โโโ tsconfig.app.json
13โ โโโ tsconfig.spec.json
14โโโ libs/
15โ โโโ <lib name>/
16โ โโโ src/
17โ โโโ ng-package.json
18โ โโโ package.json
19โ โโโ project.json
20โ โโโ README.md
21โ โโโ tsconfig.lib.json
22โ โโโ tsconfig.lib.prod.json
23โ โโโ tsconfig.spec.json
24โโโ tools/
25โโโ .editorconfig
26โโโ .gitignore
27โโโ .prettierignore
28โโโ .prettierrc
29โโโ karma.conf.js
30โโโ nx.json
31โโโ package.json
32โโโ README.md
33โโโ tsconfig.base.json
34
Modified Folder Structure
The automated migration supports Angular CLI workspaces with a standard structure, configurations and features. It supports workspaces using the following executors (builders):
@angular-devkit/build-angular:application
@angular-devkit/build-angular:browser
@angular-devkit/build-angular:browser-esbuild
@angular-devkit/build-angular:dev-server
@angular-devkit/build-angular:extract-i18n
@angular-devkit/build-angular:karma
@angular-devkit/build-angular:ng-packagr
@angular-devkit/build-angular:prerender
@angular-devkit/build-angular:protractor
@angular-devkit/build-angular:server
@angular-devkit/build-angular:ssr-dev-server
@angular-eslint/builder:lint
@cypress/schematic:cypress
@nguniversal/builders:prerender
@nguniversal/builders:ssr-dev-server
Support for other executors may be added in the future.
After migration
Your workspace is now powered by Nx! You can verify that your application still runs as intended:
- To serve, run
nx serve <app name>
. - To build, run
nx build <app name>
. - To run unit tests, run
nx test <app name>
. - To see your project graph, run
nx graph
.
Your project graph will grow as you add and use more applications and libraries. You can add the
--watch
flag tonx graph
to see the changes in-browser as you add them.
Learn More
Learn more about the advantages of Nx in the following guides:
- Using Cypress for e2e tests
- Using Jest for unit tests
- Computation Caching
- Rebuilding and Retesting What is Affected
- Integrate with Editors
- Advanced Angular Micro Frontends with Dynamic Module Federation
From Nx Console
Nx Console no longer supports the Angular CLI. Angular CLI users will receive a notice, asking if they want to switch to Nx. When you click this button, weโll run the nx init
command to set up the Nx CLI, allowing for cached builds, and for you to share this cache with your teammates via Nx Cloud.
If you're not ready to make the change yet, you can come back to this later:
- If you're using Nx Console: open the Vs Code command palette and start typing "Convert Angular CLI to Nx Workspace".
- Regardless of using Nx Console (or your IDE): run
npx nx init
from the root of your project.
Once the script has run, commit the changes. Reverting this commit will effectively undo the changes made.