Skip to content

Commit d92c94d

Browse files
bcabanesvsavkin
bcabanes
authored and
vsavkin
committed
docs(nx): add nx documentation files
This adds some documentation files splitted in different categories.
1 parent 1ea7a1d commit d92c94d

19 files changed

+1636
-0
lines changed

‎docs/documentations/affected.md

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Rebuilding and Retesting What is Affected
2+
3+
As with a regular CLI project, you can build and test apps and libs.
4+
5+
```console
6+
ng g app myapp
7+
ng g app myapp2 --directory=mydirectory
8+
ng g lib mylib
9+
ng g lib mylib2 --directory=mydirectory
10+
11+
ng build myapp
12+
ng build mydirectory-myapp2
13+
ng build mylib # work if the lib is marked as publishable
14+
ng build mydirectory-mylib2 # work if the lib is marked as publishable
15+
16+
ng test myapp # runs unit tests for myapp
17+
ng test mylib # runs unit tests for mylib
18+
ng e2e myapp-e2e # runs e2e tests for myapp
19+
```
20+
21+
Now imagine, `myapp` depends on `mylib`. If we make a change to `mylib`,
22+
we need to make sure nothing in the workspace is affected.
23+
Typically, you would do it like this:
24+
25+
```console
26+
ng build mylib
27+
ng test mylib
28+
ng build myapp
29+
ng test myapp
30+
```
31+
32+
In many organizations, you would have dozens or hundreds of apps and libs.
33+
To be productive in a monorepo, you need to be able to check that your
34+
change is safe, and rebuilding and retesting everything on every change
35+
won't scale, tracing the dependencies manually (as shown above) wont's
36+
scale either. Nx uses code analysis to determine what needs to be rebuild
37+
and retested, and it provides the following three commands you can use:
38+
`affected:build`, `affected:test`, and `affected:e2e`.
39+
40+
- Rerunning build for all the projects affected by a PR
41+
42+
```console
43+
yarn affected:build --base=master --head=HEAD
44+
```
45+
46+
- Rerunning unit tests for all the projects affected by a PR
47+
48+
```console
49+
yarn affected:test --base=master --head=HEAD
50+
```
51+
52+
- Rerunning e2e tests for all the projects affected by a PR
53+
54+
```console
55+
yarn affected:e2e --base=master --head=HEAD
56+
```
57+
58+
When executing these commands, Nx will topologically sort the projects,
59+
and will run what it can in parallel. But we can also explicitly pass
60+
`--parallel` like so:
61+
62+
```console
63+
yarn affected:build --base=master --parallel
64+
yarn affected:test --base=master --parallel
65+
yarn affected:e2e --base=master --parallel
66+
```
67+
68+
We can also pass `--maxParallel` to specify the number of parallel processes.
69+
70+
## affected:build
71+
72+
Run `npm run affected:build -- --help` or `yarn affected:build --help` to see
73+
the available options:
74+
75+
```console
76+
Build applications affected by changes
77+
78+
Run command using --base=[SHA1] (affected by the committed, uncommitted and
79+
untracked changes):
80+
--base Base of the current branch (usually master) [string]
81+
82+
or using --base=[SHA1] --head=[SHA2] (affected by the committed changes):
83+
--base Base of the current branch (usually master) [string]
84+
--head Latest commit of the current branch (usually HEAD) [string]
85+
86+
or using:
87+
--files A list of files delimited by commas [array]
88+
--uncommitted Uncommitted changes
89+
--untracked Untracked changes
90+
91+
Options:
92+
--help Show help [boolean]
93+
--version Show version number [boolean]
94+
--parallel Parallelize the command [boolean] [default: false]
95+
--maxParallel Max number of parallel processes [number] [default: 3]
96+
--all All projects
97+
--exclude Exclude certain projects from being processed
98+
[array] [default: []]
99+
--only-failed Isolate projects which previously failed
100+
[boolean] [default: false]
101+
```
102+
103+
- `npm run affected:build -- --base=[SHA1] --base=[SHA2]` or `yarn affected:build --base=[SHA1] --base=[SHA2]`. Nx will calculate what changed between the two SHAs, and will build the apps affected by the change. For instance, `yarn affected:build --base=origin/master --base=HEAD` will rebuild what is affected by a PR.
104+
- `npm run affected:build -- --files=libs/mylib/src/index.ts,libs/mylib2/src/index.ts` or `yarn affected:build --files=libs/mylib/src/index.ts,libs/mylib2/src/index.ts`. Nx will build what is affected by changing the two index files.
105+
- `npm run affected:build -- --uncommitted` or `yarn affected:build --uncommitted`. Nx will build what is affected by the uncommitted files (this is useful during development).
106+
- `npm run affected:build -- --untracked` or `yarn affected:build --untracked`. Nx will build what is affected by the untracked files (this is useful during development).
107+
108+
All other options will be passed into the underlying build command (e.g., `yarn affected:build --base=origin/master --base=HEAD --prod`).
109+
110+
## affected:test
111+
112+
Run `npm run affected:test -- --help` or `yarn affected:test --help` to see the available options:
113+
114+
```console
115+
Test applications affected by the change
116+
117+
Run command using --base=[SHA1] (affected by the committed, uncommitted and
118+
untracked changes):
119+
--base Base of the current branch (usually master) [string]
120+
121+
or using --base=[SHA1] --head=[SHA2] (affected by the committed changes):
122+
--base Base of the current branch (usually master) [string]
123+
--head Latest commit of the current branch (usually HEAD) [string]
124+
125+
or using:
126+
--files A list of files delimited by commas [array]
127+
--uncommitted Uncommitted changes
128+
--untracked Untracked changes
129+
130+
Options:
131+
--help Show help [boolean]
132+
--version Show version number [boolean]
133+
--parallel Parallelize the command [boolean] [default: false]
134+
--maxParallel Max number of parallel processes [number] [default: 3]
135+
--all All projects
136+
--exclude Exclude certain projects from being processed
137+
[array] [default: []]
138+
--only-failed Isolate projects which previously failed
139+
[boolean] [default: false]
140+
```
141+
142+
- `npm run affected:test -- --base=[SHA1] --base=[SHA2]` or `yarn affected:test --base=[SHA1] --base=[SHA2]`. Nx will calculate what changed between the two SHAs, and will test the projects affected by the change. For instance, `yarn affected:test --base=origin/master --base=HEAD` will retest what is affected by a PR.
143+
- `npm run affected:test -- --files=libs/mylib/src/index.ts,libs/mylib2/src/index.ts` or `yarn affected:test --files=libs/mylib/src/index.ts,libs/mylib2/src/index.ts`. Nx will test what is affected by changing the two index files.
144+
- `npm run affected:test -- --uncommitted` or `yarn affected:test --uncommitted`. Nx will test what is affected by the uncommitted files (this is useful during development).
145+
- `npm run affected:test -- --untracked` or `yarn affected:test --untracked`. Nx will test what is affected by the untracked files (this is useful during development).
146+
147+
All other options will be passed into the underlying test command (e.g., `yarn affected:test --base=origin/master --base=HEAD --sm=false`).
148+
149+
## affected:e2e
150+
151+
Run `npm run affected:e2e -- --help` or `yarn affected:e2e --help` to see the available options:
152+
153+
```console
154+
Run e2e tests for the applications affected by changes
155+
156+
Run command using --base=[SHA1] (affected by the committed, uncommitted and
157+
untracked changes):
158+
--base Base of the current branch (usually master) [string]
159+
160+
or using --base=[SHA1] --head=[SHA2] (affected by the committed changes):
161+
--base Base of the current branch (usually master) [string]
162+
--head Latest commit of the current branch (usually HEAD) [string]
163+
164+
or using:
165+
--files A list of files delimited by commas [array]
166+
--uncommitted Uncommitted changes
167+
--untracked Untracked changes
168+
169+
Options:
170+
--help Show help [boolean]
171+
--version Show version number [boolean]
172+
--all All projects
173+
--exclude Exclude certain projects from being processed
174+
[array] [default: []]
175+
--only-failed Isolate projects which previously failed
176+
[boolean] [default: false]
177+
```
178+
179+
- `npm run affected:e2e -- --base=[SHA1] --base=[SHA2]` or `yarn affected:e2e --base=[SHA1] --base=[SHA2]`. Nx will calculate what changed between the two SHAs, and will run e2e test for the apps affected by the change. For instance, `yarn affected:test --base=origin/master --base=HEAD` will retest what is affected by a PR.
180+
- `npm run affected:e2e -- --files=libs/mylib/src/index.ts,libs/mylib2/src/index.ts` or `yarn affected:e2e --files=libs/mylib/src/index.ts,libs/mylib2/src/index.ts`. Nx will run e2e tests for what is affected by changing the two index files.
181+
- `npm run affected:e2e -- --uncommitted` or `yarn affected:e2e --uncommitted`. Nx will run e2e tests for what is affected by the uncommitted files (this is useful during development).
182+
- `npm run affected:e2e -- --untracked` or `yarn affected:e2e --untracked`. Nx will run e2e tests for what is affected by the untracked files (this is useful during development).
183+
184+
All other options will be passed into the underlying test command (e.g., `yarn affected:test --base=origin/master --base=HEAD --sm=false`).

‎docs/documentations/applications.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Creating an App
2+
3+
Adding new apps to an Nx Workspace is done by using the Angular CLI generate command. Nx has a schematic named `app` that can be used to add a new app to our workspace:
4+
5+
```bash
6+
ng g app myapp
7+
ng generate app myapp # same thing
8+
ng generate application myapp # same thing
9+
```
10+
11+
This will create a new app, will place it in the `apps` directory, and will configure the `angular.json` and `nx.json` files to support the new app. It will also configure the root `NgModule` to import the `NxModule` code so we can take advantage of things like `DataPersistence`.
12+
13+
# Available options
14+
15+
Run `ng generate app --help` to see the list of available options:
16+
17+
```
18+
usage: ng generate app <name> [options]
19+
options:
20+
--directory
21+
The directory of the new application.
22+
--dry-run (-d)
23+
Run through without making any changes.
24+
--force (-f)
25+
Forces overwriting of files.
26+
--inline-style (-s)
27+
Specifies if the style will be in the ts file.
28+
--inline-template (-t)
29+
Specifies if the template will be in the ts file.
30+
--prefix (-p)
31+
The prefix to apply to generated HTML selector of components.
32+
--routing
33+
Generates a routing module.
34+
--skip-package-json
35+
Do not add dependencies to package.json.
36+
--skip-tests (-S)
37+
Skip creating spec files.
38+
--style
39+
The file extension to be used for style files.
40+
--tags
41+
Add tags to the application (used for linting)
42+
--view-encapsulation
43+
Specifies the view encapsulation strategy.
44+
```
45+
46+
Most of these options are identical to the ones supported by the default CLI application, but the following are new or different: `directory`, `routing`, and `tags`.
47+
48+
- `ng generate app myapp --directory=myteam` will create a new application in `apps/myteam/myapp`.
49+
- `ng generate app myapp --routing` will configure the root `NgModule` to wire up routing, as well as add a `<router-outlet>` to the AppComponent template to help get us started.
50+
- `ng generate app myapp --tags=shared,experimental` will annotate the created app with the two tags, which can be used for advanced code analysis. Read more below.

‎docs/documentations/cypress.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# What is Cypress?
2+
3+
Cypress is an open source e2e test runner that is very efficient and gives you a modern e2e testing experience. It is used within Slack internally as well as many other enterprises and open source projects including Nrwl projects!
4+
5+
## Reasons for Using Cypress
6+
7+
Cypress is architecturally different from tools like Selenium. Many things that are challenging with Selenium are straightforward using Cypress.
8+
It provides:
9+
10+
- Time Travel
11+
- Debuggability
12+
- Automatic Waiting
13+
- Spies, Stubs, and Clocks
14+
- Network Traffic Control
15+
- Consistent Results
16+
- Screenshots and Videos
17+
18+
## How to use Cypress
19+
20+
### Generating an application which uses Cypress
21+
22+
To start using Cypress, you need to provide the `--e2e-test-runner=cypress` option when creating a new application.
23+
24+
```
25+
ng generate application myApp --e2e-test-runner=cypress
26+
```
27+
28+
> Unfortunately, the cypress api and its ecosystem are different from Protractor. So Nx cannot provide a reliable migration from Protractor to Cypress tests in an existing application.
29+
30+
### Testing an application which uses Cypress
31+
32+
Testing a project using Cypress within the Nx Workspace is almost identical to testing any other project. Use the following command to execute the e2e tests in the `applicationName` application:
33+
34+
```
35+
ng e2e my-app-e2e
36+
```
37+
38+
By default, Cypress will run in the terminal but “headed” (you will see the tests executing in a new browser window), using the default browser to perform all the specs as Protractor does it. You will have the result of all the tests and errors (if any) in your terminal.
39+
40+
Screenshots and Videos will be accessible respectively in `/dist/apps/my-app-e2e/screenshots` and `/dist/apps/my-app-e2e/videos` by default.
41+
42+
### Watching for changes
43+
44+
With, `ng e2e my-app-e2e --watch` Cypress will start in the application mode.
45+
46+
Typescript will watch your spec files and recompile; Cypress will then run the new tests automatically. If you make changes in your application, the tests are triggered to run again automatically.
47+
48+
### Watching for changes (headless)
49+
50+
With, `ng e2e my-app-e2e --watch --headless` Cypress will start in the terminal in _headless_ mode. Everything will happen in the terminal and you will not be bothered by any browser window. You will be able to focus on your tests.
51+
52+
### Using Cypress headlessly (CI)
53+
54+
If you want to run the Cypress tests in headless mode (while being on CI for example), you can do so by passing `--headless` to the command. You will see all the test results live in the terminal. Videos and screenshot will be available for debugging.
55+
56+
```
57+
ng e2e my-app-e2e --headless
58+
```
59+
60+
### Test specific targeted build
61+
62+
You can run your e2e test against a production build too with `--prod`, by doing the following:
63+
64+
```
65+
ng e2e my-app-e2e --prod
66+
```
67+
68+
### Specifying a custom url to test
69+
70+
The `baseUrl` property provides you the ability to test an application hosted on a specific domain.
71+
72+
```
73+
ng e2e my-app-e2e --baseUrl=https://my-app.com
74+
```
75+
76+
> If no `baseUrl` and no `devServerTarget` are provided, Cypress will expect to have the `baseUrl` property in the `cypress.json` file, or will error.
77+
78+
## Deeper configuration (cypress.json)
79+
80+
Nx respects the way Cypress intends to normally work; it uses project configuration. If you need to fine-tune the options, you can do so by modifying the `cypress.json` file in the related project. You can easily add your `projectId` to save all the screenshot and video into your Cypress dashboard. The complete configuration is documented on [the official website](https://docs.cypress.io/guides/references/configuration.html#Options).

‎docs/documentations/dependency-diagrams.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Analysing & visualizing dependencies
2+
3+
To be able to support the monorepo-style development, the tools must know how different projects in your workspace depend on each other. Nx uses advanced code analysis to build this dependency graph.
4+
5+
You can visualize it by running `npm run dep-graph` or `yarn dep-graph`.
6+
7+
![dependency-graph](//images.ctfassets.net/8eyogtwep6d2/7M6FSiQ75K8gu8G4QqSsSa/111f85a98ed129c53a86c0edf4bd2912/dependency-graph.png)
8+
9+
You can also visualize what is affected by your change, by using the `affected:dep-graph` command.
10+
11+
![dependency-graph-affected](//images.ctfassets.net/8eyogtwep6d2/1375oQexPaKikmICIAa2q4/904272360ba3f2a3469fbeeab62efdb1/dependency-graph-affected.png)
12+
13+
# Available options
14+
15+
Run `npm run affected:dep-graph -- --help` or `yarn affected:dep-graph --help` to see the available options:
16+
17+
```
18+
Graph dependencies affected by changes
19+
20+
Run command using --base=[SHA1] --head=[SHA2]:
21+
--base Base of the current branch (usually master) [string]
22+
--head Latest commit of the current branch (usually HEAD) [string]
23+
24+
or using:
25+
--files A list of files delimited by commas [array]
26+
--uncommitted Uncommitted changes
27+
--untracked Untracked changes
28+
29+
Options:
30+
--help Show help [boolean]
31+
--version Show version number [boolean]
32+
--file output file (e.g. --file=.vis/output.json)
33+
```
34+
35+
First, you need to tell Nx what you changed, and you can do it in one of the following ways:
36+
37+
- `npm run affected:dep-graph -- --base=[SHA1] --base=[SHA2]` or `yarn affected:dep-graph --base=[SHA1] --base=[SHA2]`. Nx will calculate what changed between the two SHAs, and will graph what is affected by the change. For instance, `yarn affected:dep-graph --base=origin/master --base=HEAD` will show what is affected by a PR.
38+
- `npm run affected:dep-graph -- --files=libs/mylib/src/index.ts,libs/mylib2/src/index.ts` or `yarn affected:dep-graph --files=libs/mylib/src/index.ts,libs/mylib2/src/index.ts`. Nx will graph what is affected by changing the two index files.
39+
- `npm run affected:dep-graph -- --uncommitted` or `yarn affected:dep-graph --uncommitted`. Nx will graph what is affected by the uncommitted files (this is useful during development).
40+
- `npm run affected:dep-graph -- --untracked` or `yarn affected:dep-graph --untracked`. Nx will graph what is affected by the untracked files (this is useful during development).
41+
42+
By default, the `dep-graph` and `affected:dep-graph` commands will open the browser to show the graph, but you can also output the graph into a file by running:
43+
44+
- `npm run dep-graph -- --file=graph.json` or `yarn dep-graph --file=graph.json` will emit a json file.
45+
- `npm run dep-graph -- --file=graph.dot` or `yarn dep-graph --file=graph.dot` will emit a dot file.
46+
- `npm run dep-graph -- --file=graph.svg` or `yarn dep-graph --file=graph.svg` will emit an svg file.

0 commit comments

Comments
 (0)