Migrating an Angular application manually
Older Angular VersionsIf you are using older versions of Angular (version 13 or lower), make sure to use the appropriate version of Nx that matches your version of Angular. See the Nx and Angular Version Compatibility Matrix to find the correct version. The generated files will also be slightly different.
If you are unable to automatically transform your Angular CLI workspace to an Nx workspace, there are some manual steps you can take to move your project(s) into an Nx workspace.
Generating a new workspace
To start, run the command to generate an Nx workspace with an Angular application.
Using npx
❯
npx create-nx-workspace myorg --preset=angular-standalone
Using npm init
❯
npm init nx-workspace myorg --preset=angular-standalone
Using yarn create
❯
yarn create nx-workspace myorg --preset=angular-standalone
When prompted for the application name
, enter the project name from your current angular.json
file.
A new Nx workspace with your org name
as the folder name, and your application name
as the root-level application is generated.
1<workspace name>/
2├── e2e/
3│ ├── src/
4│ ├── .eslintrc.json
5│ ├── cypress.config.ts
6│ ├── project.json
7│ └── tsconfig.json
8├── src/
9│ ├── app/
10│ ├── assets/
11│ ├── favicon.ico
12│ ├── index.html
13│ ├── main.ts
14│ ├── styles.css
15│ └── test-setup.ts
16├── .eslintrc.json
17├── .eslintrc.base.json
18├── .gitignore
19├── .prettierignore
20├── .prettierrc
21├── jest.config.app.ts
22├── jest.config.ts
23├── jest.preset.js
24├── nx.json
25├── package.json
26├── project.json
27├── README.md
28├── tsconfig.app.json
29├── tsconfig.base.json
30├── tsconfig.editor.json
31├── tsconfig.json
32└── tsconfig.spec.json
33
Review Angular installed packages versions
Creating an Nx workspace with the latest version will install the Angular packages on their latest versions. If you're using a lower version that's supported by the latest Nx, make sure to adjust the newly generated package.json
file with your versions.
Copying over application files
Your application code is self-contained within the src
folder of your Angular CLI workspace.
- Copy the
src
folder from your Angular CLI project to theapps/<app name>
folder, overwriting the existingsrc
folder. - Copy any project-specific configuration files, such as
browserslist
, or service worker configuration files into their relative path undersrc
in the root of the repo. - Transfer the
assets
,scripts
,styles
, and build-specific configuration, such as service worker configuration, from your Angular CLIangular.json
to the root-levelproject.json
file.
Verify your application runs correctly by running:
❯
ng serve <app name>
Updating your unit testing configuration
Nx uses Jest by default. If you have any custom Jest configuration, you need to update the workspace Jest configuration also.
Verify your tests run correctly by running:
❯
ng test <app name>
If you are using Karma
for unit testing:
- Copy the
karma.conf.js
file to the root folder. - Copy the
test.ts
file to yoursrc
folder. - Copy the
test
target in yourarchitect
configuration from your Angular CLIangular.json
file into thetargets
configuration in theproject.json
file in your Nx workspace. - Run
nx format
to changearchitect
totargets
andbuilder
toexecutor
.
Jest will be used by default when generating new applications. If you want to continue using
Karma
, set theunitTestRunner
tokarma
in thegenerators
section of thenx.json
file.
- Update
test-setup.ts
totest.ts
in thefiles
array of thetsconfig.spec.json
file.
1{
2 "extends": "./tsconfig.json",
3 "compilerOptions": {
4 "outDir": "../../dist/out-tsc",
5 "types": ["jasmine", "node"]
6 },
7 "files": ["src/test.ts", "src/polyfills.ts"],
8 "include": ["**/*.spec.ts", "**/*.test.ts", "**/*.d.ts"]
9}
10
Verify your tests run correctly by running:
❯
ng test <app name>
Updating your E2E testing configuration
Nx uses Cypress by default. If you are already using Cypress, copy your E2E setup files into the apps/<app name>-e2e
folder and verify your tests still run correctly by running:
❯
ng e2e <app name>-e2e
If you are using Protractor
for E2E testing:
- Delete the
e2e
folder that was generated to use Cypress. - Copy the
e2e
folder from your Angular CLI workspace into the root folder. - Create the project configuration file at
e2e/project.json
. - Copy the project configuration for
e2e
from the Angular CLI workspaceangular.json
file toe2e/project.json
and adjust the file paths to be relative toe2e
. - Run
nx format
to changearchitect
totargets
andbuilder
toexecutor
.
Create a tsconfig.json
file under e2e
folder:
1{
2 "extends": "../tsconfig.base.json",
3 "compilerOptions": {
4 "outDir": "../dist/out-tsc"
5 }
6}
7
Update the tsconfig.app.json
to extend the root tsconfig.json
:
1{
2 "extends": "./tsconfig.json",
3 "compilerOptions": {
4 "outDir": "./dist/out-tsc",
5 "module": "commonjs",
6 "target": "es5",
7 "types": ["jasmine", "jasminewd2", "node"]
8 }
9}
10
Verify your E2E tests run correctly by running:
❯
ng e2e e2e
Cypress will be used by default when generating new applications. If you want to continue using
Protractor
, set thee2eTestRunner
toprotractor
in thegenerators
section of thenx.json
file.
Updating your linting configuration
For lint rules, migrate your existing rules into the root .eslintrc.base.json
file.
Verify your lint checks run correctly by running:
❯
npm run lint
OR
❯
yarn lint
Learn more about the advantages of Nx in the following guides:
Using Cypress for e2e tests
Using Jest for unit tests
Rebuilding and Retesting What is Affected