docs(nx): add guide on transitioning to an Nx workspace
This commit is contained in:
Brandon Roberts
Victor Savkin
parent
18d0798b13
commit
fd78f0923c
@ -14,7 +14,8 @@ With Nx, you can:
|
|||||||
|
|
||||||
- New to Nx? Have a look at the [Getting Started](/angular/getting-started/getting-started) guide.
|
- New to Nx? Have a look at the [Getting Started](/angular/getting-started/getting-started) guide.
|
||||||
- Complete the [tutorial](/angular/tutorial/01-create-application) on using Nx build a full stack application.
|
- Complete the [tutorial](/angular/tutorial/01-create-application) on using Nx build a full stack application.
|
||||||
- Use the [Nx CLI](/angular/guides/cli) to perform various development tasks.
|
- Use the [Angular CLI](https://angular.io/cli) to perform various development tasks.
|
||||||
|
- Transform an [Angular CLI workspace into an Nx workspace](/angular/guides/transition-to-nx).
|
||||||
- Learn more about Nx from books, blog posts, talks on our [resources page](/angular/getting-started/resources).
|
- Learn more about Nx from books, blog posts, talks on our [resources page](/angular/getting-started/resources).
|
||||||
|
|
||||||
## Contribute
|
## Contribute
|
||||||
|
|||||||
363
docs/angular/guides/transition-to-nx.md
Normal file
363
docs/angular/guides/transition-to-nx.md
Normal file
@ -0,0 +1,363 @@
|
|||||||
|
# Transitioning to Nx
|
||||||
|
|
||||||
|
Within an Nx workspace, you gain many capabilities that help you build applications and libraries
|
||||||
|
using a monorepo approach. If you are currently using an Angular CLI workspace, you can transform it into an Nx workspace.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- The major version of your `Angular CLI` must align with the version of `Nx` you are upgrading to. For example, if you're using Angular CLI version 7, you must transition using the latest version 7 release of Nx.
|
||||||
|
- Currently, transforming an Angular CLI workspace to an Nx workspace automatically only supports a single project. If you have more than one project in your Angular CLI workspace, you can still migrate manually.
|
||||||
|
|
||||||
|
## Using ng add
|
||||||
|
|
||||||
|
To transform a Angular CLI workspace to an Nx workspace, use the `ng add` command:
|
||||||
|
|
||||||
|
```
|
||||||
|
ng add @nrwl/workspace
|
||||||
|
```
|
||||||
|
|
||||||
|
This installs the `@nrwl/workspace` package into your workspace and runs a schematic to transform your workspace. The schematic applies the following changes to your workspace:
|
||||||
|
|
||||||
|
- Installs the packages for the `Nx` plugin `@nrwl/angular` in your package.json.
|
||||||
|
- Creates an [nx.json](/angular/fundamentals/monorepos-automation#understanding-nx-json) file in the root of your workspace.
|
||||||
|
- Creates configuration files for [Prettier](/angular/fundamentals/use-modern-tools#prettier).
|
||||||
|
- Creates an `apps` folder for generating applications.
|
||||||
|
- Creates a `libs` folder for generating libraries.
|
||||||
|
- Creates a `tools` folder that includes files for custom workspace tooling, such as workspace-specific schematics and scripts.
|
||||||
|
- Moves your application into the `apps` folder, and updates the relevant file paths in your configuration files.
|
||||||
|
- Moves your e2e suite into the `apps/{{app name}}-e2e` folder, and updates the relevant file paths in your configuration files.
|
||||||
|
- Updates your `package.json` with scripts to run various `Nx` workspace commands.
|
||||||
|
- Updates your `angular.json` configuration to reflect the new paths.
|
||||||
|
|
||||||
|
After the changes are applied, your workspace file structure should look similar to below:
|
||||||
|
|
||||||
|
```treeview
|
||||||
|
<workspace name>/
|
||||||
|
├── apps/
|
||||||
|
│ ├── <app name>/
|
||||||
|
│ │ ├── src/
|
||||||
|
│ │ │ ├── app/
|
||||||
|
│ │ │ ├── assets/
|
||||||
|
│ │ │ ├── environments/
|
||||||
|
│ │ │ ├── favicon.ico
|
||||||
|
│ │ │ ├── index.html
|
||||||
|
│ │ │ ├── main.ts
|
||||||
|
│ │ │ ├── polyfills.ts
|
||||||
|
│ │ │ ├── styles.css
|
||||||
|
│ │ │ └── test.ts
|
||||||
|
│ │ ├── browserslist
|
||||||
|
│ │ ├── karma.conf.js
|
||||||
|
│ │ ├── tsconfig.app.json
|
||||||
|
│ │ └── tsconfig.spec.json
|
||||||
|
│ └── <app name>-e2e/
|
||||||
|
│ ├── src/
|
||||||
|
│ ├── protractor.conf.js
|
||||||
|
│ └── tsconfig.json
|
||||||
|
├── libs/
|
||||||
|
├── tools/
|
||||||
|
├── README.md
|
||||||
|
├── angular.json
|
||||||
|
├── nx.json
|
||||||
|
├── package.json
|
||||||
|
└── tsconfig.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Your workspace is now powered by Nx! You can verify out that your application still runs as intended:
|
||||||
|
|
||||||
|
- To serve, run `ng serve`.
|
||||||
|
- To build, run `ng build`.
|
||||||
|
- To run unit tests, run `ng test`.
|
||||||
|
- To run e2e tests, run `ng e2e`.
|
||||||
|
- To see your dependency graph, run `nx dep-graph`.
|
||||||
|
|
||||||
|
> Your dependency graph will grow as you add, and use more applications and libraries.
|
||||||
|
|
||||||
|
Learn more about the advantages of Nx in the following guides:
|
||||||
|
|
||||||
|
[Using Cypress for e2e tests](/angular/guides/modernize-cypress) \
|
||||||
|
[Using Jest for unit tests](/angular/guides/modernize-jest) \
|
||||||
|
[Rebuilding and Retesting What is Affected](/angular/guides/monorepo-affected)
|
||||||
|
|
||||||
|
## Transitioning Manually
|
||||||
|
|
||||||
|
If you are unable to automatically transform your Angular CLI workspace to an Nx workspace using the [ng add](/angular/guides/transition-to-nx#using-ng-add) method, 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`**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx create-nx-workspace myorg --preset=angular
|
||||||
|
```
|
||||||
|
|
||||||
|
**Using `npm init`**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm init nx-workspace myorg --preset=angular
|
||||||
|
```
|
||||||
|
|
||||||
|
**Using `yarn create`**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
yarn create nx-workspace myorg --preset=angular
|
||||||
|
```
|
||||||
|
|
||||||
|
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 first application is generated.
|
||||||
|
|
||||||
|
```treeview
|
||||||
|
<workspace name>/
|
||||||
|
├── apps/
|
||||||
|
│ ├── <app name>/
|
||||||
|
│ │ ├── src/
|
||||||
|
│ │ │ ├── app/
|
||||||
|
│ │ │ ├── assets/
|
||||||
|
│ │ │ ├── environments/
|
||||||
|
│ │ │ ├── favicon.ico
|
||||||
|
│ │ │ ├── index.html
|
||||||
|
│ │ │ ├── main.ts
|
||||||
|
│ │ │ ├── polyfills.ts
|
||||||
|
│ │ │ ├── styles.css
|
||||||
|
│ │ │ └── test.ts
|
||||||
|
│ │ ├── browserslist
|
||||||
|
│ │ ├── jest.conf.js
|
||||||
|
│ │ ├── tsconfig.app.json
|
||||||
|
│ │ ├── tsconfig.json
|
||||||
|
│ │ ├── tslint.json
|
||||||
|
│ │ └── tsconfig.spec.json
|
||||||
|
│ └── <app name>-e2e/
|
||||||
|
│ ├── src/
|
||||||
|
│ ├── cypress.json
|
||||||
|
│ ├── tsconfig.e2e.json
|
||||||
|
│ ├── tslint.json
|
||||||
|
│ └── tsconfig.json
|
||||||
|
├── libs/
|
||||||
|
├── tools/
|
||||||
|
├── .prettierignore
|
||||||
|
├── .prettierrc
|
||||||
|
├── README.md
|
||||||
|
├── angular.json
|
||||||
|
├── jest.config.js
|
||||||
|
├── nx.json
|
||||||
|
├── package.json
|
||||||
|
├── tsconfig.json
|
||||||
|
└── tslint.json
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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 the `apps/<app name>` folder, overwriting the existing `src` folder.
|
||||||
|
- Copy any project-specific files, such as `browserslist`, or service worker configuration files into their relative path under the `apps/<app name>` folder.
|
||||||
|
- Transfer the `assets`, `scripts`, `styles`, and build-specific configuration, such as service worker configuration, from your Angular CLI `angular.json` to the Nx workspace `angular.json` file.
|
||||||
|
|
||||||
|
Verify your app runs correctly by running:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
ng test <app name>
|
||||||
|
```
|
||||||
|
|
||||||
|
If you are using `Karma` for unit testing:
|
||||||
|
|
||||||
|
- Copy the `karma.conf.js` file to your `apps/<app name>` folder.
|
||||||
|
- Copy the `test.ts` file to your `apps/<app name>/src` folder.
|
||||||
|
- Copy the `test` target in your `architect` configuration from your Angular CLI `angular.json` file into your Nx workspace `angular.json` file.
|
||||||
|
- Update your `test` target to prepend `apps/<app name>` to each of the file paths.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": 1,
|
||||||
|
"projects": {
|
||||||
|
"<app name>": {
|
||||||
|
"projectType": "application",
|
||||||
|
"schematics": {},
|
||||||
|
"root": "apps/<app name>",
|
||||||
|
"sourceRoot": "apps/<app name>/src",
|
||||||
|
"prefix": "myapp",
|
||||||
|
"architect": {
|
||||||
|
"test": {
|
||||||
|
"builder": "@angular-devkit/build-angular:karma",
|
||||||
|
"options": {
|
||||||
|
"main": "apps/<app name>/src/test.ts",
|
||||||
|
"polyfills": "apps/<app name>/src/polyfills.ts",
|
||||||
|
"tsConfig": "apps/<app name>/tsconfig.spec.json",
|
||||||
|
"karmaConfig": "apps/<app name>/karma.conf.js",
|
||||||
|
"assets": [
|
||||||
|
"apps/<app name>/src/favicon.ico",
|
||||||
|
"apps/<app name>/src/assets"
|
||||||
|
],
|
||||||
|
"styles": ["apps/<app name>/src/styles.css"],
|
||||||
|
"scripts": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"cli": {
|
||||||
|
"defaultCollection": "@nrwl/angular"
|
||||||
|
},
|
||||||
|
"schematics": {
|
||||||
|
"@nrwl/angular:application": {
|
||||||
|
"unitTestRunner": "jest",
|
||||||
|
"e2eTestRunner": "cypress"
|
||||||
|
},
|
||||||
|
"@nrwl/angular:library": {
|
||||||
|
"unitTestRunner": "jest"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"defaultProject": "<app name>"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> Jest will be used by default when generating new applications. If you want to continue using `Karma`, set the `unitTestRunner` to `karma` in the `schematics` section of the `angular.json` file.
|
||||||
|
|
||||||
|
- Update `test-setup.ts` to `test.ts` in the `files` array of the `apps/<app name>/tsconfig.spec.json` file.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"extends": "./tsconfig.json",
|
||||||
|
"compilerOptions": {
|
||||||
|
"outDir": "../../dist/out-tsc",
|
||||||
|
"module": "commonjs",
|
||||||
|
"types": ["node"]
|
||||||
|
},
|
||||||
|
"files": ["src/test.ts", "src/polyfills.ts"],
|
||||||
|
"include": ["**/*.spec.ts", "**/*.d.ts"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Verify your tests run correctly by running:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
ng e2e <app name>-e2e
|
||||||
|
```
|
||||||
|
|
||||||
|
If you are using `Protractor` for E2E testing:
|
||||||
|
|
||||||
|
- Delete the `apps/<app name>-e2e` folder that was generated to use Cypress.
|
||||||
|
- Copy the `e2e` folder from your Angular CLI workspace into the `apps` file to your `apps/<app name>` folder.
|
||||||
|
- Rename the `e2e` folder to `<app name>-e2e`.
|
||||||
|
- In the Nx workspace `angular.json`, update your `<app name>-e2e` project with the `Protractor` configuration.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": 1,
|
||||||
|
"projects": {
|
||||||
|
"<app name>-e2e": {
|
||||||
|
"root": "apps/<app name>-e2e",
|
||||||
|
"projectType": "application",
|
||||||
|
"architect": {
|
||||||
|
"e2e": {
|
||||||
|
"builder": "@angular-devkit/build-angular:protractor",
|
||||||
|
"options": {
|
||||||
|
"protractorConfig": "apps/<app name>-e2e/protractor.conf.js",
|
||||||
|
"devServerTarget": "<app name>:serve"
|
||||||
|
},
|
||||||
|
"configurations": {
|
||||||
|
"production": {
|
||||||
|
"devServerTarget": "<app name>:serve:production"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"lint": {
|
||||||
|
"builder": "@angular-devkit/build-angular:tslint",
|
||||||
|
"options": {
|
||||||
|
"tsConfig": "apps/<app name>-e2e/tsconfig.e2e.json",
|
||||||
|
"exclude": ["**/node_modules/**", "!apps/<app name>-e2e/**"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"cli": {
|
||||||
|
"defaultCollection": "@nrwl/angular"
|
||||||
|
},
|
||||||
|
"schematics": {
|
||||||
|
"@nrwl/angular:application": {
|
||||||
|
"unitTestRunner": "jest",
|
||||||
|
"e2eTestRunner": "cypress"
|
||||||
|
},
|
||||||
|
"@nrwl/angular:library": {
|
||||||
|
"unitTestRunner": "jest"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"defaultProject": "<app name>"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Create a `tsconfig.e2e.json` file under `apps/<app name>-e2e` folder:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"extends": "./tsconfig.json",
|
||||||
|
"compilerOptions": {
|
||||||
|
"outDir": "../../dist/out-tsc"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Update the `apps/<app name>/tsconfig.json` to extend the root `tsconfig.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"extends": "../../tsconfig.json",
|
||||||
|
"compilerOptions": {
|
||||||
|
"outDir": "../../out-tsc/<app name>-e2e",
|
||||||
|
"module": "commonjs",
|
||||||
|
"target": "es5",
|
||||||
|
"types": ["jasmine", "jasminewd2", "node"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Verify your E2E tests run correctly by running:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
ng e2e <app name>-e2e
|
||||||
|
```
|
||||||
|
|
||||||
|
> Cypress will be used by default when generating new applications. If you want to continue using `Protractor`, set the `e2eTestRunner` to `protractor` in the `schematics` section of the `angular.json` file.
|
||||||
|
|
||||||
|
### Updating your linting configuration
|
||||||
|
|
||||||
|
For lint rules, migrate your existing rules into the root `tslint.json` file.
|
||||||
|
|
||||||
|
Verify your lint checks run correctly by running:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm run lint
|
||||||
|
```
|
||||||
|
|
||||||
|
OR
|
||||||
|
|
||||||
|
```sh
|
||||||
|
yarn lint
|
||||||
|
```
|
||||||
|
|
||||||
|
Learn more about the advantages of Nx in the following guides:
|
||||||
|
|
||||||
|
[Using Cypress for e2e tests](/angular/guides/modernize-cypress) \
|
||||||
|
[Using Jest for unit tests](/angular/guides/modernize-jest) \
|
||||||
|
[Rebuilding and Retesting What is Affected](/angular/guides/monorepo-affected)
|
||||||
@ -105,6 +105,10 @@
|
|||||||
"name": "Guides",
|
"name": "Guides",
|
||||||
"id": "guides",
|
"id": "guides",
|
||||||
"itemList": [
|
"itemList": [
|
||||||
|
{
|
||||||
|
"name": "Transitioning to Nx",
|
||||||
|
"id": "transition-to-nx"
|
||||||
|
},
|
||||||
{
|
{
|
||||||
"name": "Using Cypress",
|
"name": "Using Cypress",
|
||||||
"id": "modernize-cypress",
|
"id": "modernize-cypress",
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user