miel.truyen/nx
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

docs(core): move "nx connect" earlier in CI section for standalone/monorepo tutorials (#26845)

Browse Source 
We're making an enhancement to `nx g ci-workflow` such that when the
workspace is already connected to Nx Cloud, we'll enable distribution in
the workflow file, rather than having them commented out. For the flow
of the tutorial, it makes more sense to do `nx connect` first so things
are set up correctly without user intervention.

Note: I left the "Make sure the following line is uncommented" for
distribution because older versions will still leave it uncommented.

Example:
https://nx-dev-git-docs-tutorials-update-nrwl.vercel.app/getting-started/tutorials/angular-monorepo-tutorial

---------

Co-authored-by: Isaac Mann <isaacplmann@gmail.com>
This commit is contained in:
Jack Hsu 2024-07-19 13:43:05 -04:00 committed by GitHub
parent 188f0d8526
commit ec5b04fb82
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
15 changed files with 720 additions and 413 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
docs/shared/migration/adding-to-existing-project.md
View File

@ -293,53 +293,93 @@ This tutorial walked you through how Nx can improve the local development experi
- Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute. - Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute.
- Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks). - Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks).
### Generate a CI Workflow
If you are starting a new project, you can use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
{% callout type="note" title="Choose your CI provider" %}
You can choose `github`, `circleci`, `azure`, `bitbucket-pipelines`, or `gitlab` for the `ci` flag.
{% /callout %}
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR.
The key line in the CI pipeline is:
```yml
- run: npx nx affected -t lint test build e2e-ci
```
### Connect to Nx Cloud ### Connect to Nx Cloud
Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more. Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more.
To connect to Nx Cloud: Now that we're working on the CI pipeline, it is important for your changes to be pushed to a GitHub repository.
- Commit and push your changes 1. Commit your existing changes with `git add . && git commit -am "updates"`
- Go to [https://cloud.nx.app](https://cloud.nx.app), create an account, and connect your repository 2. [Create a new GitHub repository](https://github.com/new)
3. Follow GitHub's instructions to push your existing code to the repository
#### Connect to Nx Cloud Manually Now connect your repository to Nx Cloud with the following command:
If you are not able to connect via the automated process at [https://cloud.nx.app](https://cloud.nx.app), you can connect your workspace manually by running:
```shell ```shell
npx nx connect npx nx connect
``` ```
You will then need to merge your changes and connect to your workspace on [https://cloud.nx.app](https://cloud.nx.app). A browser window will open to register your repository in your [Nx Cloud](https://cloud.nx.app) account. The link is also printed to the terminal if the windows does not open, or you closed it before finishing the steps. The app will guide you to create a PR to enable Nx Cloud on your repository.
### Enable a Distributed CI Pipeline ![](/shared/tutorials/nx-cloud-github-connect.avif)
The current CI pipeline runs on a single machine and can only handle small workspaces. To transform your CI into a CI that runs on multiple machines and can handle workspaces of any size, uncomment the `npx nx-cloud start-ci-run` line in the `.github/workflows/ci.yml` file. Once the PR is created, merge it into your main branch.
```yml ![](/shared/tutorials/github-cloud-pr-merged.avif)
- run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
And make sure you pull the latest changes locally:
```shell
git pull
``` ```
You should now have an `nxCloudAccessToken` property specified in the `nx.json` file.
### Create a CI Workflow
Use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR. Since we are using Nx Cloud, the pipeline will also distribute tasks across multiple machines to ensure fast and reliable CI runs.
The key lines in the CI pipeline are:
```yml {% fileName=".github/workflows/ci.yml" highlightLines=["10-14", "21-22"] %}
name: CI
# ...
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# This enables task distribution via Nx Cloud
# Run this command as early as possible, before dependencies are installed
# Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
# Connect your workspace by running "nx connect" and uncomment this
- run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
- uses: actions/setup-node@v3
with:
node-version: 20
cache: 'npm'
- run: npm ci --legacy-peer-deps
- uses: nrwl/nx-set-shas@v4
# Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
- run: npx nx affected -t lint test build
```
### Open a Pull Request
Commit the changes and open a new PR on GitHub.
```shell
git add .
git commit -m 'add CI workflow file'
git push origin add-workflow
```
When you view the PR on GitHub, you will see a comment from Nx Cloud that reports on the status of the CI run.
![Nx Cloud report](/shared/tutorials/github-pr-cloud-report.avif)
The `See all runs` link goes to a page with the progress and results of tasks that were run in the CI pipeline.
![Run details](/shared/tutorials/nx-cloud-run-details.avif)
For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials: For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials:
- [Circle CI with Nx](/ci/intro/tutorials/circle) - [Circle CI with Nx](/ci/intro/tutorials/circle)

102
docs/shared/migration/adding-to-monorepo.md
View File

@ -316,53 +316,93 @@ This tutorial walked you through how Nx can improve the local development experi
- Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute. - Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute.
- Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks). - Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks).
### Generate a CI Workflow
If you are starting a new project, you can use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
{% callout type="note" title="Choose your CI provider" %}
You can choose `github`, `circleci`, `azure`, `bitbucket-pipelines`, or `gitlab` for the `ci` flag.
{% /callout %}
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR.
The key line in the CI pipeline is:
```yml
- run: npx nx affected -t lint test build e2e-ci
```
### Connect to Nx Cloud ### Connect to Nx Cloud
Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more. Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more.
To connect to Nx Cloud: Now that we're working on the CI pipeline, it is important for your changes to be pushed to a GitHub repository.
- Commit and push your changes 1. Commit your existing changes with `git add . && git commit -am "updates"`
- Go to [https://cloud.nx.app](https://cloud.nx.app), create an account, and connect your repository 2. [Create a new GitHub repository](https://github.com/new)
3. Follow GitHub's instructions to push your existing code to the repository
#### Connect to Nx Cloud Manually Now connect your repository to Nx Cloud with the following command:
If you are not able to connect via the automated process at [https://cloud.nx.app](https://cloud.nx.app), you can connect your workspace manually by running:
```shell ```shell
npx nx connect npx nx connect
``` ```
You will then need to merge your changes and connect to your workspace on [https://cloud.nx.app](https://cloud.nx.app). A browser window will open to register your repository in your [Nx Cloud](https://cloud.nx.app) account. The link is also printed to the terminal if the windows does not open, or you closed it before finishing the steps. The app will guide you to create a PR to enable Nx Cloud on your repository.
### Enable a Distributed CI Pipeline ![](/shared/tutorials/nx-cloud-github-connect.avif)
The current CI pipeline runs on a single machine and can only handle small workspaces. To transform your CI into a CI that runs on multiple machines and can handle workspaces of any size, uncomment the `npx nx-cloud start-ci-run` line in the `.github/workflows/ci.yml` file. Once the PR is created, merge it into your main branch.
```yml ![](/shared/tutorials/github-cloud-pr-merged.avif)
- run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
And make sure you pull the latest changes locally:
```shell
git pull
``` ```
You should now have an `nxCloudAccessToken` property specified in the `nx.json` file.
### Create a CI Workflow
Use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR. Since we are using Nx Cloud, the pipeline will also distribute tasks across multiple machines to ensure fast and reliable CI runs.
The key lines in the CI pipeline are:
```yml {% fileName=".github/workflows/ci.yml" highlightLines=["10-14", "21-22"] %}
name: CI
# ...
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# This enables task distribution via Nx Cloud
# Run this command as early as possible, before dependencies are installed
# Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
# Connect your workspace by running "nx connect" and uncomment this
- run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
- uses: actions/setup-node@v3
with:
node-version: 20
cache: 'npm'
- run: npm ci --legacy-peer-deps
- uses: nrwl/nx-set-shas@v4
# Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
- run: npx nx affected -t lint test build
```
### Open a Pull Request
Commit the changes and open a new PR on GitHub.
```shell
git add .
git commit -m 'add CI workflow file'
git push origin add-workflow
```
When you view the PR on GitHub, you will see a comment from Nx Cloud that reports on the status of the CI run.
![Nx Cloud report](/shared/tutorials/github-pr-cloud-report.avif)
The `See all runs` link goes to a page with the progress and results of tasks that were run in the CI pipeline.
![Run details](/shared/tutorials/nx-cloud-run-details.avif)
For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials: For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials:
- [Circle CI with Nx](/ci/intro/tutorials/circle) - [Circle CI with Nx](/ci/intro/tutorials/circle)

102
docs/shared/migration/migration-angular.md
View File

@ -117,53 +117,93 @@ This tutorial walked you through how Nx can improve the local development experi
- Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute. - Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute.
- Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks). - Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks).
### Generate a CI Workflow
If you are starting a new project, you can use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
{% callout type="note" title="Choose your CI provider" %}
You can choose `github`, `circleci`, `azure`, `bitbucket-pipelines`, or `gitlab` for the `ci` flag.
{% /callout %}
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR.
The key line in the CI pipeline is:
```yml
- run: npx nx affected -t lint test build e2e-ci
```
### Connect to Nx Cloud ### Connect to Nx Cloud
Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more. Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more.
To connect to Nx Cloud: Now that we're working on the CI pipeline, it is important for your changes to be pushed to a GitHub repository.
- Commit and push your changes 1. Commit your existing changes with `git add . && git commit -am "updates"`
- Go to [https://cloud.nx.app](https://cloud.nx.app), create an account, and connect your repository 2. [Create a new GitHub repository](https://github.com/new)
3. Follow GitHub's instructions to push your existing code to the repository
#### Connect to Nx Cloud Manually Now connect your repository to Nx Cloud with the following command:
If you are not able to connect via the automated process at [https://cloud.nx.app](https://cloud.nx.app), you can connect your workspace manually by running:
```shell ```shell
npx nx connect npx nx connect
``` ```
You will then need to merge your changes and connect to your workspace on [https://cloud.nx.app](https://cloud.nx.app). A browser window will open to register your repository in your [Nx Cloud](https://cloud.nx.app) account. The link is also printed to the terminal if the windows does not open, or you closed it before finishing the steps. The app will guide you to create a PR to enable Nx Cloud on your repository.
### Enable a Distributed CI Pipeline ![](/shared/tutorials/nx-cloud-github-connect.avif)
The current CI pipeline runs on a single machine and can only handle small workspaces. To transform your CI into a CI that runs on multiple machines and can handle workspaces of any size, uncomment the `npx nx-cloud start-ci-run` line in the `.github/workflows/ci.yml` file. Once the PR is created, merge it into your main branch.
```yml ![](/shared/tutorials/github-cloud-pr-merged.avif)
- run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
And make sure you pull the latest changes locally:
```shell
git pull
``` ```
You should now have an `nxCloudAccessToken` property specified in the `nx.json` file.
### Create a CI Workflow
Use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR. Since we are using Nx Cloud, the pipeline will also distribute tasks across multiple machines to ensure fast and reliable CI runs.
The key lines in the CI pipeline are:
```yml {% fileName=".github/workflows/ci.yml" highlightLines=["10-14", "21-22"] %}
name: CI
# ...
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# This enables task distribution via Nx Cloud
# Run this command as early as possible, before dependencies are installed
# Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
# Connect your workspace by running "nx connect" and uncomment this
- run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
- uses: actions/setup-node@v3
with:
node-version: 20
cache: 'npm'
- run: npm ci --legacy-peer-deps
- uses: nrwl/nx-set-shas@v4
# Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
- run: npx nx affected -t lint test build
```
### Open a Pull Request
Commit the changes and open a new PR on GitHub.
```shell
git add .
git commit -m 'add CI workflow file'
git push origin add-workflow
```
When you view the PR on GitHub, you will see a comment from Nx Cloud that reports on the status of the CI run.
![Nx Cloud report](/shared/tutorials/github-pr-cloud-report.avif)
The `See all runs` link goes to a page with the progress and results of tasks that were run in the CI pipeline.
![Run details](/shared/tutorials/nx-cloud-run-details.avif)
For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials: For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials:
- [Circle CI with Nx](/ci/intro/tutorials/circle) - [Circle CI with Nx](/ci/intro/tutorials/circle)

132
docs/shared/tutorials/angular-monorepo.md
View File

@ -60,10 +60,10 @@ NX Let's create a new workspace [https://nx.dev/getting-started/intro]
✔ Default stylesheet format · css ✔ Default stylesheet format · css
✔ Do you want to enable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering)? · No ✔ Do you want to enable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering)? · No
✔ Test runner to use for end to end (E2E) tests · cypress ✔ Test runner to use for end to end (E2E) tests · cypress
✔ Do you want Nx Cloud to make your CI fast? · Yes ✔ Which CI provider would you like to use? · github
``` ```
Let's name the initial application `angular-store`. In this tutorial we're going to use `cypress` for e2e tests and `css` for styling. The above command generates the following structure: Let's name the initial application `angular-store`. In this tutorial we're going to use `cypress` for e2e tests and `css` for styling. We'll talk more about how Nx integrates with GitHub Actions later in the tutorial. The above command generates the following structure:
``` ```
└─ angular-monorepo └─ angular-monorepo
@ -117,7 +117,7 @@ The [`nx.json` file](/reference/nx-json) contains configuration settings for Nx
To serve your new Angular application, just run: To serve your new Angular application, just run:
```shell ```shell
nx serve angular-store npx nx serve angular-store
``` ```
Your application should be served at [http://localhost:4200](http://localhost:4200). Your application should be served at [http://localhost:4200](http://localhost:4200).
@ -315,9 +315,9 @@ Nx allows you to separate this logic into "local libraries". The main benefits i
Let's assume our domain areas include `products`, `orders` and some more generic design system components, called `ui`. We can generate a new library for each of these areas using the Angular library generator: Let's assume our domain areas include `products`, `orders` and some more generic design system components, called `ui`. We can generate a new library for each of these areas using the Angular library generator:
``` ```
nx g @nx/angular:library products --directory=libs/products --standalone npx nx g @nx/angular:library products --directory=libs/products --standalone
nx g @nx/angular:library orders --directory=libs/orders --standalone npx nx g @nx/angular:library orders --directory=libs/orders --standalone
nx g @nx/angular:library shared-ui --directory=libs/shared/ui --standalone npx nx g @nx/angular:library shared-ui --directory=libs/shared/ui --standalone
``` ```
Note how we type out the full path in the `directory` flag to place the libraries into a subfolder. You can choose whatever folder structure you like to organize your projects. If you change your mind later, you can run the [move generator](/nx-api/workspace/generators/move) to move a project to a different folder. Note how we type out the full path in the `directory` flag to place the libraries into a subfolder. You can choose whatever folder structure you like to organize your projects. If you change your mind later, you can run the [move generator](/nx-api/workspace/generators/move) to move a project to a different folder.
@ -360,7 +360,7 @@ Running the above commands should lead to the following directory structure:
Each of these libraries Each of these libraries
- has its own `project.json` file with corresponding targets you can run (e.g. running tests for just orders: `nx test orders`) - has its own `project.json` file with corresponding targets you can run (e.g. running tests for just orders: `npx nx test orders`)
- has the name you specified in the generate command; you can find the name in the corresponding `project.json` file - has the name you specified in the generate command; you can find the name in the corresponding `project.json` file
- has a dedicated `index.ts` file which is the "public API" of the library - has a dedicated `index.ts` file which is the "public API" of the library
- is mapped in the `tsconfig.base.json` at the root of the workspace - is mapped in the `tsconfig.base.json` at the root of the workspace
@ -434,7 +434,7 @@ export const appRoutes: Route[] = [
]; ];
``` ```
Serving your app (`nx serve angular-store`) and then navigating to `/products` should give you the following result: Serving your app (`npx nx serve angular-store`) and then navigating to `/products` should give you the following result:
![products route](/shared/tutorials/app-products-route.png) ![products route](/shared/tutorials/app-products-route.png)
@ -493,12 +493,12 @@ export class AppComponent {
<!-- {% video-link link="https://youtu.be/OQ-Zc5tcxJE?t=1416" /%} --> <!-- {% video-link link="https://youtu.be/OQ-Zc5tcxJE?t=1416" /%} -->
Nx automatically detects the dependencies between the various parts of your workspace and builds a [project graph](/features/explore-graph). This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like `nx build`, identifying [affected projects](/features/run-tasks#run-tasks-on-projects-affected-by-a-pr) and more. Interestingly you can also visualize it. Nx automatically detects the dependencies between the various parts of your workspace and builds a [project graph](/features/explore-graph). This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like `npx nx build`, identifying [affected projects](/features/run-tasks#run-tasks-on-projects-affected-by-a-pr) and more. Interestingly you can also visualize it.
Just run: Just run:
```shell ```shell
nx graph npx nx graph
``` ```
You should be able to see something similar to the following in your browser. You should be able to see something similar to the following in your browser.
@ -592,7 +592,7 @@ You should be able to see something similar to the following in your browser.
Notice how `shared-ui` is not yet connected to anything because we didn't import it in any of our projects. Notice how `shared-ui` is not yet connected to anything because we didn't import it in any of our projects.
Exercise for you: change the codebase such that `shared-ui` is used by `orders` and `products`. Note: you need to restart the `nx graph` command to update the graph visualization or run the CLI command with the `--watch` flag. Exercise for you: change the codebase such that `shared-ui` is used by `orders` and `products`. Note: you need to restart the `npx nx graph` command to update the graph visualization or run the CLI command with the `--watch` flag.
## Testing and Linting ## Testing and Linting
@ -601,9 +601,9 @@ Exercise for you: change the codebase such that `shared-ui` is used by `orders`
Our current setup not only has targets for serving and building the Angular application, but also has targets for unit testing, e2e testing and linting. The `test` and `lint` targets are defined in the application `project.json` file, while the `e2e` target is [inferred from the `apps/angular-store-e2e/cypress.config.ts` file](#inferred-tasks). We can use the same syntax as before to run these tasks: Our current setup not only has targets for serving and building the Angular application, but also has targets for unit testing, e2e testing and linting. The `test` and `lint` targets are defined in the application `project.json` file, while the `e2e` target is [inferred from the `apps/angular-store-e2e/cypress.config.ts` file](#inferred-tasks). We can use the same syntax as before to run these tasks:
```bash ```bash
nx test angular-store # runs the tests for angular-store npx nx test angular-store # runs the tests for angular-store
nx lint inventory # runs the linter on inventory npx nx lint inventory # runs the linter on inventory
nx e2e angular-store-e2e # runs e2e tests for the angular-store npx nx e2e angular-store-e2e # runs e2e tests for the angular-store
``` ```
### Inferred Tasks ### Inferred Tasks
@ -611,7 +611,7 @@ nx e2e angular-store-e2e # runs e2e tests for the angular-store
Nx identifies available tasks for your project from [tooling configuration files](/concepts/inferred-tasks), `package.json` scripts and the targets defined in `project.json`. All tasks from the `angular-store` project are defined in its `project.json` file, but the companion `angular-store-e2e` project has its tasks inferred from configuration files. To view the tasks that Nx has detected, look in the [Nx Console](/getting-started/editor-setup), [Project Details View](/recipes/nx-console/console-project-details) or run: Nx identifies available tasks for your project from [tooling configuration files](/concepts/inferred-tasks), `package.json` scripts and the targets defined in `project.json`. All tasks from the `angular-store` project are defined in its `project.json` file, but the companion `angular-store-e2e` project has its tasks inferred from configuration files. To view the tasks that Nx has detected, look in the [Nx Console](/getting-started/editor-setup), [Project Details View](/recipes/nx-console/console-project-details) or run:
```shell ```shell
nx show project angular-store-e2e --web npx nx show project angular-store-e2e --web
``` ```
{% project-details title="Project Details View" height="100px" %} {% project-details title="Project Details View" height="100px" %}
@ -873,7 +873,7 @@ You can also override the settings for inferred tasks by modifying the [`targetD
In addition to running individual tasks, you can also run multiple tasks in parallel using the following syntax: In addition to running individual tasks, you can also run multiple tasks in parallel using the following syntax:
```shell ```shell
nx run-many -t test lint e2e npx nx run-many -t test lint e2e
``` ```
### Caching ### Caching
@ -882,7 +882,7 @@ One thing to highlight is that Nx is able to [cache the tasks you run](/features
Note that all of these targets are automatically cached by Nx. If you re-run a single one or all of them again, you'll see that the task completes immediately. In addition, (as can be seen in the output example below) there will be a note that a matching cache result was found and therefore the task was not run again. Note that all of these targets are automatically cached by Nx. If you re-run a single one or all of them again, you'll see that the task completes immediately. In addition, (as can be seen in the output example below) there will be a note that a matching cache result was found and therefore the task was not run again.
```{% command="nx run-many -t test lint e2e" path="angular-monorepo" %} ```{% command="npx nx run-many -t test lint e2e" path="angular-monorepo" %}
✔ nx run e2e:lint [existing outputs match the cache, left as is] ✔ nx run e2e:lint [existing outputs match the cache, left as is]
✔ nx run angular-store:lint [existing outputs match the cache, left as is] ✔ nx run angular-store:lint [existing outputs match the cache, left as is]
✔ nx run angular-store:test [existing outputs match the cache, left as is] ✔ nx run angular-store:test [existing outputs match the cache, left as is]
@ -915,7 +915,7 @@ And then make a small change to the `products` library.
One of the key features of Nx in a monorepo setting is that you're able to run tasks only for projects that are actually affected by the code changes that you've made. To run the tests for only the projects affected by this change, run: One of the key features of Nx in a monorepo setting is that you're able to run tasks only for projects that are actually affected by the code changes that you've made. To run the tests for only the projects affected by this change, run:
```shell ```shell
nx affected -t test npx nx affected -t test
``` ```
Note that the unit tests were run for `products`, `angular-store` and `inventory`, but not for `orders` because a change to `products` can not possibly break the tests for `orders`. In a small repo like this, there isn't a lot of time saved, but as there are more tests and more projects, this quickly becomes an essential command. Note that the unit tests were run for `products`, `angular-store` and `inventory`, but not for `orders` because a change to `products` can not possibly break the tests for `orders`. In a small repo like this, there isn't a lot of time saved, but as there are more tests and more projects, this quickly becomes an essential command.
@ -923,7 +923,7 @@ Note that the unit tests were run for `products`, `angular-store` and `inventory
You can also see what projects are affected in the graph visualizer with; You can also see what projects are affected in the graph visualizer with;
```shell ```shell
nx graph --affected npx nx graph --affected
``` ```
{% graph height="450px" %} {% graph height="450px" %}
@ -1062,10 +1062,10 @@ Replace the `command` with whatever terminal command you use to deploy your site
The `"dependsOn": "build"` setting tells Nx to make sure that the project's `build` task has been run successfully before the `deploy` task. The `"dependsOn": "build"` setting tells Nx to make sure that the project's `build` task has been run successfully before the `deploy` task.
With the `deploy` tasks defined, you can deploy a single application with `nx deploy angular-store` or deploy any applications affected by the current changes with: With the `deploy` tasks defined, you can deploy a single application with `npx nx deploy angular-store` or deploy any applications affected by the current changes with:
```shell ```shell
nx affected -t deploy npx nx affected -t deploy
``` ```
## Imposing Constraints with Module Boundary Rules ## Imposing Constraints with Module Boundary Rules
@ -1193,7 +1193,7 @@ export class ProductsComponent {}
If you lint your workspace you'll get an error now: If you lint your workspace you'll get an error now:
```{% command="nx run-many -t lint" %} ```{% command="npx nx run-many -t lint" %}
NX Running target lint for 7 projects NX Running target lint for 7 projects
✖ nx run products:lint ✖ nx run products:lint
Linting "products"... Linting "products"...
@ -1241,53 +1241,79 @@ This tutorial walked you through how Nx can improve the local development experi
- Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute. - Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute.
- Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks). - Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks).
### Generate a CI Workflow
If you are starting a new project, you can use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
{% callout type="note" title="Choose your CI provider" %}
You can choose `github`, `circleci`, `azure`, `bitbucket-pipelines`, or `gitlab` for the `ci` flag.
{% /callout %}
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR.
The key line in the CI pipeline is:
```yml
- run: npx nx affected -t lint test build e2e-ci
```
### Connect to Nx Cloud ### Connect to Nx Cloud
Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more. Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more.
To connect to Nx Cloud: Now that we're working on the CI pipeline, it is important for your changes to be pushed to a GitHub repository.
- Commit and push your changes 1. Commit your existing changes with `git add . && git commit -am "updates"`
- Go to [https://cloud.nx.app](https://cloud.nx.app), create an account, and connect your repository 2. [Create a new GitHub repository](https://github.com/new)
3. Follow GitHub's instructions to push your existing code to the repository
#### Connect to Nx Cloud Manually When we set up the repository at the beginning of this tutorial, we chose to use GitHub Actions as a CI provider. This created a basic CI pipeline and configured Nx Cloud in the repository. It also printed a URL in the terminal to register your repository in your [Nx Cloud](https://cloud.nx.app) account. If you didn't click on the link when first creating your repository, you can show it again by running:
If you are not able to connect via the automated process at [https://cloud.nx.app](https://cloud.nx.app), you can connect your workspace manually by running:
```shell ```shell
npx nx connect npx nx connect
``` ```
You will then need to merge your changes and connect to your workspace on [https://cloud.nx.app](https://cloud.nx.app). Once you click the link, follow the steps provided and make sure Nx Cloud is enabled on the main branch of your repository.
### Enable a Distributed CI Pipeline ### Configure Your CI Workflow
The current CI pipeline runs on a single machine and can only handle small workspaces. To transform your CI into a CI that runs on multiple machines and can handle workspaces of any size, uncomment the `npx nx-cloud start-ci-run` line in the `.github/workflows/ci.yml` file. When you chose GitHub Actions as your CI provider at the beginning of the tutorial, `create-nx-workspace` created a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR. Since we are using Nx Cloud, the pipeline will also distribute tasks across multiple machines to ensure fast and reliable CI runs.
```yml If you need to generate a new workflow file for GitHub Actions or other providers, you can do so with this command:
- run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
```shell
npx nx generate ci-workflow
``` ```
The key lines in the CI pipeline are:
```yml {% fileName=".github/workflows/ci.yml" highlightLines=["10-14", "21-22"] %}
name: CI
# ...
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# This enables task distribution via Nx Cloud
# Run this command as early as possible, before dependencies are installed
# Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
# Connect your workspace by running "nx connect" and uncomment this
- run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
- uses: actions/setup-node@v3
with:
node-version: 20
cache: 'npm'
- run: npm ci --legacy-peer-deps
- uses: nrwl/nx-set-shas@v4
# Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
- run: npx nx affected -t lint test build
```
### Open a Pull Request
Commit the changes and open a new PR on GitHub.
```shell
git add .
git commit -m 'add CI workflow file'
git push origin add-workflow
```
When you view the PR on GitHub, you will see a comment from Nx Cloud that reports on the status of the CI run.
![Nx Cloud report](/shared/tutorials/github-pr-cloud-report.avif)
The `See all runs` link goes to a page with the progress and results of tasks that were run in the CI pipeline.
![Run details](/shared/tutorials/nx-cloud-run-details.avif)
For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials: For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials:
- [Circle CI with Nx](/ci/intro/tutorials/circle) - [Circle CI with Nx](/ci/intro/tutorials/circle)

92
docs/shared/tutorials/angular-standalone.md
View File

@ -43,13 +43,13 @@ NX Let's create a new workspace [https://nx.dev/getting-started/intro]
✔ Default stylesheet format · css ✔ Default stylesheet format · css
✔ Do you want to enable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering)? · No ✔ Do you want to enable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering)? · No
✔ Test runner to use for end to end (E2E) tests · cypress ✔ Test runner to use for end to end (E2E) tests · cypress
✔ Set up CI with caching, distribution and test deflaking · github ✔ Which CI provider would you like to use? · github
``` ```
You get asked a few questions that help Nx preconfigure your new Angular application. These include: You get asked a few questions that help Nx preconfigure your new Angular application. These include:
- Angular specific questions, such as which bundler to use, whether to enable server-side rendering and which stylesheet format to use - Angular specific questions, such as which bundler to use, whether to enable server-side rendering and which stylesheet format to use
- General Nx questions, such as whether to enable remote caching with Nx Cloud. Nx comes with built-in [local caching](/features/cache-task-results). If you want to benefit from this cache in CI, you can enable [remote caching](/ci/features/remote-cache) which will set up [Nx Cloud](https://nx.app). This is also a prerequisite for enabling [distributed task execution](/ci/features/distribute-task-execution). - General Nx questions, such as whether to enable remote caching with Nx Cloud. Nx comes with built-in [local caching](/features/cache-task-results). If you want to benefit from this cache in CI, you can enable [remote caching](/ci/features/remote-cache) which will set up [Nx Cloud](https://nx.app). This is also a prerequisite for enabling [distributed task execution](/ci/features/distribute-task-execution). We'll explore this later in the tutorial.
For the sake of this tutorial, let's respond to all the questions with the default response. For the sake of this tutorial, let's respond to all the questions with the default response.
@ -1050,53 +1050,79 @@ This tutorial walked you through how Nx can improve the local development experi
- Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute. - Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute.
- Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks). - Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks).
### Generate a CI Workflow
If you are starting a new project, you can use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
{% callout type="note" title="Choose your CI provider" %}
You can choose `github`, `circleci`, `azure`, `bitbucket-pipelines`, or `gitlab` for the `ci` flag.
{% /callout %}
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR.
The key line in the CI pipeline is:
```yml
- run: npx nx affected -t lint test build e2e-ci
```
### Connect to Nx Cloud ### Connect to Nx Cloud
Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more. Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more.
To connect to Nx Cloud: Now that we're working on the CI pipeline, it is important for your changes to be pushed to a GitHub repository.
- Commit and push your changes 1. Commit your existing changes with `git add . && git commit -am "updates"`
- Go to [https://cloud.nx.app](https://cloud.nx.app), create an account, and connect your repository 2. [Create a new GitHub repository](https://github.com/new)
3. Follow GitHub's instructions to push your existing code to the repository
#### Connect to Nx Cloud Manually When we set up the repository at the beginning of this tutorial, we chose to use GitHub Actions as a CI provider. This created a basic CI pipeline and configured Nx Cloud in the repository. It also printed a URL in the terminal to register your repository in your [Nx Cloud](https://cloud.nx.app) account. If you didn't click on the link when first creating your repository, you can show it again by running:
If you are not able to connect via the automated process at [https://cloud.nx.app](https://cloud.nx.app), you can connect your workspace manually by running:
```shell ```shell
npx nx connect npx nx connect
``` ```
You will then need to merge your changes and connect to your workspace on [https://cloud.nx.app](https://cloud.nx.app). Once you click the link, follow the steps provided and make sure Nx Cloud is enabled on the main branch of your repository.
### Enable a Distributed CI Pipeline ### Configure Your CI Workflow
The current CI pipeline runs on a single machine and can only handle small workspaces. To transform your CI into a CI that runs on multiple machines and can handle workspaces of any size, uncomment the `npx nx-cloud start-ci-run` line in the `.github/workflows/ci.yml` file. When you chose GitHub Actions as your CI provider at the beginning of the tutorial, `create-nx-workspace` created a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR. Since we are using Nx Cloud, the pipeline will also distribute tasks across multiple machines to ensure fast and reliable CI runs.
```yml If you need to generate a new workflow file for GitHub Actions or other providers, you can do so with this command:
- run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
```shell
npx nx generate ci-workflow
``` ```
The key lines in the CI pipeline are:
```yml {% fileName=".github/workflows/ci.yml" highlightLines=["10-14", "21-22"] %}
name: CI
# ...
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# This enables task distribution via Nx Cloud
# Run this command as early as possible, before dependencies are installed
# Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
# Connect your workspace by running "nx connect" and uncomment this
- run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
- uses: actions/setup-node@v3
with:
node-version: 20
cache: 'npm'
- run: npm ci --legacy-peer-deps
- uses: nrwl/nx-set-shas@v4
# Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
- run: npx nx affected -t lint test build
```
### Open a Pull Request
Commit the changes and open a new PR on GitHub.
```shell
git add .
git commit -m 'add CI workflow file'
git push origin add-workflow
```
When you view the PR on GitHub, you will see a comment from Nx Cloud that reports on the status of the CI run.
![Nx Cloud report](/shared/tutorials/github-pr-cloud-report.avif)
The `See all runs` link goes to a page with the progress and results of tasks that were run in the CI pipeline.
![Run details](/shared/tutorials/nx-cloud-run-details.avif)
For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials: For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials:
- [Circle CI with Nx](/ci/intro/tutorials/circle) - [Circle CI with Nx](/ci/intro/tutorials/circle)

BIN
docs/shared/tutorials/github-cloud-pr-merged.avif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
docs/shared/tutorials/github-pr-cloud-report.avif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
docs/shared/tutorials/gradle-github-pr-cloud-report.avif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

108
docs/shared/tutorials/gradle.md
View File

@ -269,55 +269,97 @@ This tutorial walked you through how Nx can improve the local development experi
- Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute. - Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute.
- Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks). - Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks).
### Generate a CI Workflow
If you are starting a new project, you can use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
{% callout type="note" title="Choose your CI provider" %}
You can choose `github`, `circleci`, `azure`, `bitbucket-pipelines`, or `gitlab` for the `ci` flag.
{% /callout %}
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR.
The key line in the CI pipeline is:
```yml
- run: npx nx affected -t lint test build e2e-ci
```
### Connect to Nx Cloud ### Connect to Nx Cloud
Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more. Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more.
To connect to Nx Cloud: Now that we're working on the CI pipeline, it is important for your changes to be pushed to a GitHub repository.
- Commit and push your changes 1. Commit your existing changes with `git add . && git commit -am "updates"`
- Go to [https://cloud.nx.app](https://cloud.nx.app), create an account, and connect your repository 2. [Create a new GitHub repository](https://github.com/new)
3. Follow GitHub's instructions to push your existing code to the repository
#### Connect to Nx Cloud Manually Now connect your repository to Nx Cloud with the following command:
If you are not able to connect via the automated process at [https://cloud.nx.app](https://cloud.nx.app), you can connect your workspace manually by running:
```shell ```shell
npx nx connect npx nx connect
``` ```
You will then need to merge your changes and connect to your workspace on [https://cloud.nx.app](https://cloud.nx.app). A browser window will open to register your repository in your [Nx Cloud](https://cloud.nx.app) account. The link is also printed to the terminal if the windows does not open, or you closed it before finishing the steps. The app will guide you to create a PR to enable Nx Cloud on your repository.
### Enable a Distributed CI Pipeline ![](/shared/tutorials/nx-cloud-github-connect.avif)
The current CI pipeline runs on a single machine and can only handle small workspaces. To transform your CI into a CI that runs on multiple machines and can handle workspaces of any size, uncomment the `npx nx-cloud start-ci-run` line in the `.github/workflows/ci.yml` file. Once the PR is created, merge it into your main branch.
```yml ![](/shared/tutorials/github-cloud-pr-merged.avif)
# Connect your workspace on nx.app and uncomment this to enable task distribution.
# The "--stop-agents-after" is optional, but allows idle agents to shut down once the "build" targets have been requested And make sure you pull the latest changes locally:
- run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-jvm" --stop-agents-after="build"
```shell
git pull
``` ```
You should now have an `nxCloudAccessToken` property specified in the `nx.json` file.
### Create a CI Workflow
Let's create a branch to add a CI workflow.
```shell
git checkout -b add-workflow
```
And use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR. Since we are using Nx Cloud, the pipeline will also distribute tasks across multiple machines to ensure fast and reliable CI runs.
The key lines in the CI pipeline are:
```yml {% fileName=".github/workflows/ci.yml" highlightLines=["10-14", "21-22"] %}
name: CI
# ...
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# This enables task distribution via Nx Cloud
# Run this command as early as possible, before dependencies are installed
# Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
# Connect your workspace by running "nx connect" and uncomment this
- run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
- uses: actions/setup-node@v3
with:
node-version: 20
cache: 'npm'
- run: npm ci --legacy-peer-deps
- uses: nrwl/nx-set-shas@v4
# Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
- run: npx nx affected -t lint test build
```
### Open a Pull Request
Commit the changes and open a new PR on GitHub.
```shell
git add .
git commit -m 'add CI workflow file'
git push origin add-workflow
```
When you view the PR on GitHub, you will see a comment from Nx Cloud that reports on the status of the CI run.
![Nx Cloud report](/shared/tutorials/gradle-github-pr-cloud-report.avif)
The `See all runs` link goes to a page with the progress and results of tasks that were run in the CI pipeline.
![Gradle run details](/shared/tutorials/gradle-run-details.webp) ![Gradle run details](/shared/tutorials/gradle-run-details.webp)
For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials: For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials:

159
docs/shared/tutorials/npm-workspaces.md
View File

@ -49,35 +49,8 @@ Now let's try running some tasks. To lint the `demo` app, use the `lint` npm scr
If you try to build the `demo` app, it will fail. If you try to build the `demo` app, it will fail.
```text {% command="npm run build -w @tuskdesign/demo" path="~/tuskydesigns" %} ```text
> @tuskdesign/demo@0.0.0 prebuild
> npm run typecheck
> @tuskdesign/demo@0.0.0 typecheck
> tsc
> @tuskdesign/demo@0.0.0 build
> vite build
vite v5.0.12 building for production...
✓ 4 modules transformed.
[commonjs--resolver] Failed to resolve entry for package "@tuskdesign/buttons". The package may have incorrect main/module/exports specified in its package.json.
error during build:
Error: Failed to resolve entry for package "@tuskdesign/buttons". The package may have incorrect main/module/exports specified in its package.json. Error: Failed to resolve entry for package "@tuskdesign/buttons". The package may have incorrect main/module/exports specified in its package.json.
at packageEntryFailure (file:///Users/isaac/Documents/code/tuskydesign/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:29443:17)
at resolvePackageEntry (file:///Users/isaac/Documents/code/tuskydesign/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:29440:5)
at tryNodeResolve (file:///Users/isaac/Documents/code/tuskydesign/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:29210:20)
at Object.resolveId (file:///Users/isaac/Documents/code/tuskydesign/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:28978:28)
at file:///Users/isaac/Documents/code/tuskydesign/node_modules/vite/node_modules/rollup/dist/es/shared/node-entry.js:19579:40
at async PluginDriver.hookFirstAndGetPlugin (file:///Users/isaac/Documents/code/tuskydesign/node_modules/vite/node_modules/rollup/dist/es/shared/node-entry.js:19479:28)
at async resolveId (file:///Users/isaac/Documents/code/tuskydesign/node_modules/vite/node_modules/rollup/dist/es/shared/node-entry.js:18149:26)
at async ModuleLoader.resolveId (file:///Users/isaac/Documents/code/tuskydesign/node_modules/vite/node_modules/rollup/dist/es/shared/node-entry.js:18563:15)
at async Object.resolveId (file:///Users/isaac/Documents/code/tuskydesign/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:8141:10)
at async PluginDriver.hookFirstAndGetPlugin (file:///Users/isaac/Documents/code/tuskydesign/node_modules/vite/node_modules/rollup/dist/es/shared/node-entry.js:19479:28)
npm ERR! Lifecycle script `build` failed with error:
npm ERR! Error: command failed
npm ERR! in workspace: @tuskdesign/demo@0.0.0
npm ERR! at location: /Users/isaac/Documents/code/tuskydesign/apps/demo
``` ```
The `build` script fails because it needs the `buttons` and `forms` projects to be built first in order to work correctly. To do this, lets return to the root of the repository and run the `build` task for every project in the repo: The `build` script fails because it needs the `buttons` and `forms` projects to be built first in order to work correctly. To do this, lets return to the root of the repository and run the `build` task for every project in the repo:
@ -115,38 +88,12 @@ Second, the script asks a series of questions to help set up caching for you.
- `Does the "lint" script create any outputs?` - Enter nothing - `Does the "lint" script create any outputs?` - Enter nothing
- `Would you like remote caching to make your build faster?` - Choose `Skip for now` - `Would you like remote caching to make your build faster?` - Choose `Skip for now`
```text {% command="npx nx@latest init" path="~/tuskydesigns" %}
NX Recommended Plugins:
Add these Nx plugins to integrate with the tools used in your workspace.
✔ Which plugins would you like to add? · No items were selected
NX 🐳 Nx initialization
NX 🧑‍🔧 Please answer the following questions about the scripts found in your workspace in order to generate task runner configuration
✔ Which scripts need to be run in order? (e.g. before building a project, dependent projects must be built) · build
✔ Which scripts are cacheable? (Produce the same output given the same input, e.g. build, test and lint usually are, serve and start are not) · typecheck, build, lint
✔ Does the "typecheck" script create any outputs? If not, leave blank, otherwise provide a path relative to a project root (e.g. dist, lib, build, coverage) ·
✔ Does the "build" script create any outputs? If not, leave blank, otherwise provide a path relative to a project root (e.g. dist, lib, build, coverage) · dist
✔ Does the "lint" script create any outputs? If not, leave blank, otherwise provide a path relative to a project root (e.g. dist, lib, build, coverage) ·
✔ Would you like remote caching to make your build faster? · skip
...
NX 👀 Explore Your Workspace
Run "nx graph" to show the graph of the workspace. It will show tasks that you can run with Nx.
Read this guide on exploring your workspace: https://nx.dev/features/explore-graph
```
## Explore Your Workspace ## Explore Your Workspace
If you run `nx graph` as instructed, you'll see the dependencies between your projects. If you run `nx graph` as instructed, you'll see the dependencies between your projects.
```shell {% path="~/tuskydesigns" %} ```shell {% path="~/tuskydesigns" %}
npx nx graph npx nx graph --focus=@tuskdesign/demo
``` ```
{% graph title="Tusk Design" height="200px" jsonFile="shared/tutorials/npm-workspaces-project-graph.json" %} {% graph title="Tusk Design" height="200px" jsonFile="shared/tutorials/npm-workspaces-project-graph.json" %}
@ -386,53 +333,93 @@ This tutorial walked you through how Nx can improve the local development experi
- Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute. - Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute.
- Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks). - Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks).
### Generate a CI Workflow
If you are starting a new project, you can use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
{% callout type="note" title="Choose your CI provider" %}
You can choose `github`, `circleci`, `azure`, `bitbucket-pipelines`, or `gitlab` for the `ci` flag.
{% /callout %}
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR.
The key line in the CI pipeline is:
```yml
- run: npx nx affected -t lint test build
```
### Connect to Nx Cloud ### Connect to Nx Cloud
Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more. Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more.
To connect to Nx Cloud: Now that we're working on the CI pipeline, it is important for your changes to be pushed to a GitHub repository.
- Commit and push your changes to GitHub 1. Commit your existing changes with `git add . && git commit -am "updates"`
- Go to [https://cloud.nx.app](https://cloud.nx.app), create an account, and connect your repository 2. [Create a new GitHub repository](https://github.com/new)
3. Follow GitHub's instructions to push your existing code to the repository
#### Connect to Nx Cloud Manually Now connect your repository to Nx Cloud with the following command:
If you are not able to connect via the automated process at [nx.app](https://cloud.nx.app), you can connect your workspace manually by running:
```shell ```shell
npx nx connect npx nx connect
``` ```
You will then need to merge your changes and connect to your workspace on [https://cloud.nx.app](https://cloud.nx.app). A browser window will open to register your repository in your [Nx Cloud](https://cloud.nx.app) account. The link is also printed to the terminal if the windows does not open, or you closed it before finishing the steps. The app will guide you to create a PR to enable Nx Cloud on your repository.
### Enable a Distributed CI Pipeline ![](/shared/tutorials/nx-cloud-github-connect.avif)
The current CI pipeline runs on a single machine and can only handle small workspaces. To transform your CI into a CI that runs on multiple machines and can handle workspaces of any size, uncomment the `npx nx-cloud start-ci-run` line in the `.github/workflows/ci.yml` file. Once the PR is created, merge it into your main branch.
```yml ![](/shared/tutorials/github-cloud-pr-merged.avif)
- run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
And make sure you pull the latest changes locally:
```shell
git pull
``` ```
You should now have an `nxCloudAccessToken` property specified in the `nx.json` file.
### Create a CI Workflow
Use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR. Since we are using Nx Cloud, the pipeline will also distribute tasks across multiple machines to ensure fast and reliable CI runs.
The key lines in the CI pipeline are:
```yml {% fileName=".github/workflows/ci.yml" highlightLines=["10-14", "21-22"] %}
name: CI
# ...
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# This enables task distribution via Nx Cloud
# Run this command as early as possible, before dependencies are installed
# Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
# Connect your workspace by running "nx connect" and uncomment this
- run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
- uses: actions/setup-node@v3
with:
node-version: 20
cache: 'npm'
- run: npm ci --legacy-peer-deps
- uses: nrwl/nx-set-shas@v4
# Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
- run: npx nx affected -t lint test build
```
### Open a Pull Request
Commit the changes and open a new PR on GitHub.
```shell
git add .
git commit -m 'add CI workflow file'
git push origin add-workflow
```
When you view the PR on GitHub, you will see a comment from Nx Cloud that reports on the status of the CI run.
![Nx Cloud report](/shared/tutorials/github-pr-cloud-report.avif)
The `See all runs` link goes to a page with the progress and results of tasks that were run in the CI pipeline.
![Run details](/shared/tutorials/nx-cloud-run-details.avif)
For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials: For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials:
- [Circle CI with Nx](/ci/intro/tutorials/circle) - [Circle CI with Nx](/ci/intro/tutorials/circle)

BIN
docs/shared/tutorials/nx-cloud-github-connect.avif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
docs/shared/tutorials/nx-cloud-run-details.avif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

132
docs/shared/tutorials/react-monorepo.md
View File

@ -61,10 +61,10 @@ NX Let's create a new workspace [https://nx.dev/getting-started/intro]
✔ Which bundler would you like to use? · vite ✔ Which bundler would you like to use? · vite
✔ Test runner to use for end to end (E2E) tests · cypress ✔ Test runner to use for end to end (E2E) tests · cypress
✔ Default stylesheet format · css ✔ Default stylesheet format · css
✔ Do you want Nx Cloud to make your CI fast? · Yes ✔ Which CI provider would you like to use? · GitHub Actions
``` ```
Let's name the initial application `react-store`. In this tutorial we're going to use `vite` as a bundler, `cypress` for e2e tests and `css` for styling. The above command generates the following structure: Let's name the initial application `react-store`. In this tutorial we're going to use `vite` as a bundler, `cypress` for e2e tests and `css` for styling. We'll talk more about how Nx integrates with GitHub Actions later in the tutorial. The above command generates the following structure:
``` ```
└─ react-monorepo └─ react-monorepo
@ -114,7 +114,7 @@ The [`nx.json` file](/reference/nx-json) contains configuration settings for Nx
To serve your new React application, just run: To serve your new React application, just run:
```shell ```shell
nx serve react-store npx nx serve react-store
``` ```
Your application should be served at [http://localhost:4200](http://localhost:4200). Your application should be served at [http://localhost:4200](http://localhost:4200).
@ -128,7 +128,7 @@ Nx uses the following syntax to run tasks:
Nx identifies available tasks for your project from [tooling configuration files](/concepts/inferred-tasks), `package.json` scripts and the targets defined in `project.json`. To view the tasks that Nx has detected, look in the [Nx Console](/getting-started/editor-setup) project detail view or run: Nx identifies available tasks for your project from [tooling configuration files](/concepts/inferred-tasks), `package.json` scripts and the targets defined in `project.json`. To view the tasks that Nx has detected, look in the [Nx Console](/getting-started/editor-setup) project detail view or run:
```shell ```shell
nx show project react-store npx nx show project react-store
``` ```
{% project-details title="Project Details View (Simplified)" height="100px" %} {% project-details title="Project Details View (Simplified)" height="100px" %}
@ -355,9 +355,9 @@ Nx allows you to separate this logic into "local libraries". The main benefits i
Let's assume our domain areas include `products`, `orders` and some more generic design system components, called `ui`. We can generate a new library for each of these areas using the React library generator: Let's assume our domain areas include `products`, `orders` and some more generic design system components, called `ui`. We can generate a new library for each of these areas using the React library generator:
``` ```
nx g @nx/react:library products --directory=libs/products --unitTestRunner=vitest --bundler=none npx nx g @nx/react:library products --directory=libs/products --unitTestRunner=vitest --bundler=none
nx g @nx/react:library orders --directory=libs/orders --unitTestRunner=vitest --bundler=none npx nx g @nx/react:library orders --directory=libs/orders --unitTestRunner=vitest --bundler=none
nx g @nx/react:library shared-ui --directory=libs/shared/ui --unitTestRunner=vitest --bundler=none npx nx g @nx/react:library shared-ui --directory=libs/shared/ui --unitTestRunner=vitest --bundler=none
``` ```
Note how we type out the full path in the `directory` flag to place the libraries into a subfolder. You can choose whatever folder structure you like to organize your projects. If you change your mind later, you can run the [move generator](/nx-api/workspace/generators/move) to move a project to a different folder. Note how we type out the full path in the `directory` flag to place the libraries into a subfolder. You can choose whatever folder structure you like to organize your projects. If you change your mind later, you can run the [move generator](/nx-api/workspace/generators/move) to move a project to a different folder.
@ -401,7 +401,7 @@ Running the above commands should lead to the following directory structure:
Each of these libraries Each of these libraries
- has a project details view where you can see the available tasks (e.g. running tests for just orders: `nx test orders`) - has a project details view where you can see the available tasks (e.g. running tests for just orders: `npx nx test orders`)
- has its own `project.json` file where you can customize targets - has its own `project.json` file where you can customize targets
- has the name you specified in the generate command; you can find the name in the corresponding `project.json` file - has the name you specified in the generate command; you can find the name in the corresponding `project.json` file
- has a dedicated `index.ts` file which is the "public API" of the library - has a dedicated `index.ts` file which is the "public API" of the library
@ -507,7 +507,7 @@ export function App() {
export default App; export default App;
``` ```
Serving your app (`nx serve react-store`) and then navigating to `/products` should give you the following result: Serving your app (`npx nx serve react-store`) and then navigating to `/products` should give you the following result:
![products route](/shared/tutorials/react-tutorial-products-route.png) ![products route](/shared/tutorials/react-tutorial-products-route.png)
@ -555,12 +555,12 @@ export default App;
<!-- {% video-link link="https://youtu.be/OQ-Zc5tcxJE?t=1416" /%} --> <!-- {% video-link link="https://youtu.be/OQ-Zc5tcxJE?t=1416" /%} -->
Nx automatically detects the dependencies between the various parts of your workspace and builds a [project graph](/features/explore-graph). This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like `nx build`, identifying [affected projects](/features/run-tasks#run-tasks-on-projects-affected-by-a-pr) and more. Interestingly you can also visualize it. Nx automatically detects the dependencies between the various parts of your workspace and builds a [project graph](/features/explore-graph). This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like `npx nx build`, identifying [affected projects](/features/run-tasks#run-tasks-on-projects-affected-by-a-pr) and more. Interestingly you can also visualize it.
Just run: Just run:
```shell ```shell
nx graph npx nx graph
``` ```
You should be able to see something similar to the following in your browser. You should be able to see something similar to the following in your browser.
@ -654,7 +654,7 @@ You should be able to see something similar to the following in your browser.
Notice how `shared-ui` is not yet connected to anything because we didn't import it in any of our projects. Notice how `shared-ui` is not yet connected to anything because we didn't import it in any of our projects.
Exercise for you: change the codebase such that `shared-ui` is used by `orders` and `products`. Note: you need to restart the `nx graph` command to update the graph visualization or run the CLI command with the `--watch` flag. Exercise for you: change the codebase such that `shared-ui` is used by `orders` and `products`. Note: you need to restart the `npx nx graph` command to update the graph visualization or run the CLI command with the `--watch` flag.
## Testing and Linting - Running Multiple Tasks ## Testing and Linting - Running Multiple Tasks
@ -663,15 +663,15 @@ Exercise for you: change the codebase such that `shared-ui` is used by `orders`
Our current setup doesn't just come with targets for serving and building the React application, but also has targets for unit testing, e2e testing and linting. Again, these are defined in the `project.json` file. We can use the same syntax as before to run these tasks: Our current setup doesn't just come with targets for serving and building the React application, but also has targets for unit testing, e2e testing and linting. Again, these are defined in the `project.json` file. We can use the same syntax as before to run these tasks:
```bash ```bash
nx test react-store # runs the tests for react-store npx nx test react-store # runs the tests for react-store
nx lint inventory # runs the linter on inventory npx nx lint inventory # runs the linter on inventory
nx e2e react-store-e2e # runs e2e tests for the react-store npx nx e2e react-store-e2e # runs e2e tests for the react-store
``` ```
More conveniently, we can also run tasks in parallel using the following syntax: More conveniently, we can also run tasks in parallel using the following syntax:
```shell ```shell
nx run-many -t test npx nx run-many -t test
``` ```
### Caching ### Caching
@ -680,7 +680,7 @@ One thing to highlight is that Nx is able to [cache the tasks you run](/features
Note that all of these targets are automatically cached by Nx. If you re-run a single one or all of them again, you'll see that the task completes immediately. In addition, (as can be seen in the output example below) there will be a note that a matching cache result was found and therefore the task was not run again. Note that all of these targets are automatically cached by Nx. If you re-run a single one or all of them again, you'll see that the task completes immediately. In addition, (as can be seen in the output example below) there will be a note that a matching cache result was found and therefore the task was not run again.
```{% command="nx run-many -t test lint e2e" path="react-monorepo" %} ```{% command="npx nx run-many -t test lint e2e" path="react-monorepo" %}
✔ nx run e2e:lint [existing outputs match the cache, left as is] ✔ nx run e2e:lint [existing outputs match the cache, left as is]
✔ nx run react-store:lint [existing outputs match the cache, left as is] ✔ nx run react-store:lint [existing outputs match the cache, left as is]
✔ nx run react-store:test [existing outputs match the cache, left as is] ✔ nx run react-store:test [existing outputs match the cache, left as is]
@ -723,7 +723,7 @@ export default Products;
One of the key features of Nx in a monorepo setting is that you're able to run tasks only for projects that are actually affected by the code changes that you've made. To run the tests for only the projects affected by this change, run: One of the key features of Nx in a monorepo setting is that you're able to run tasks only for projects that are actually affected by the code changes that you've made. To run the tests for only the projects affected by this change, run:
```shell ```shell
nx affected -t test npx nx affected -t test
``` ```
Note that the unit tests were run for `products`, `react-store` and `inventory`, but not for `orders` because a change to `products` can not possibly break the tests for `orders`. In a small repo like this, there isn't a lot of time saved, but as there are more tests and more projects, this quickly becomes an essential command. Note that the unit tests were run for `products`, `react-store` and `inventory`, but not for `orders` because a change to `products` can not possibly break the tests for `orders`. In a small repo like this, there isn't a lot of time saved, but as there are more tests and more projects, this quickly becomes an essential command.
@ -731,7 +731,7 @@ Note that the unit tests were run for `products`, `react-store` and `inventory`,
You can also see what projects are affected in the graph visualizer with; You can also see what projects are affected in the graph visualizer with;
```shell ```shell
nx graph --affected npx nx graph --affected
``` ```
{% graph height="450px" %} {% graph height="450px" %}
@ -865,10 +865,10 @@ Replace the `command` with whatever terminal command you use to deploy your site
The `"dependsOn": ["build"]` setting tells Nx to make sure that the project's `build` task has been run successfully before the `deploy` task. The `"dependsOn": ["build"]` setting tells Nx to make sure that the project's `build` task has been run successfully before the `deploy` task.
With the `deploy` tasks defined, you can deploy a single application with `nx deploy react-store` or deploy any applications affected by the current changes with: With the `deploy` tasks defined, you can deploy a single application with `npx nx deploy react-store` or deploy any applications affected by the current changes with:
```shell ```shell
nx affected -t deploy npx nx affected -t deploy
``` ```
## Imposing Constraints with Module Boundary Rules ## Imposing Constraints with Module Boundary Rules
@ -993,7 +993,7 @@ export default Products;
If you lint your workspace you'll get an error now: If you lint your workspace you'll get an error now:
```{% command="nx run-many -t lint" %} ```{% command="npx nx run-many -t lint" %}
Running target lint for 7 projects Running target lint for 7 projects
✖ nx run products:lint ✖ nx run products:lint
Linting "products"... Linting "products"...
@ -1039,53 +1039,79 @@ This tutorial walked you through how Nx can improve the local development experi
- Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute. - Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute.
- Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks). - Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks).
### Generate a CI Workflow
If you are starting a new project, you can use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
{% callout type="note" title="Choose your CI provider" %}
You can choose `github`, `circleci`, `azure`, `bitbucket-pipelines`, or `gitlab` for the `ci` flag.
{% /callout %}
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR.
The key line in the CI pipeline is:
```yml
- run: npx nx affected -t lint test build e2e-ci
```
### Connect to Nx Cloud ### Connect to Nx Cloud
Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more. Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more.
To connect to Nx Cloud: Now that we're working on the CI pipeline, it is important for your changes to be pushed to a GitHub repository.
- Commit and push your changes 1. Commit your existing changes with `git add . && git commit -am "updates"`
- Go to [https://cloud.nx.app](https://cloud.nx.app), create an account, and connect your repository 2. [Create a new GitHub repository](https://github.com/new)
3. Follow GitHub's instructions to push your existing code to the repository
#### Connect to Nx Cloud Manually When we set up the repository at the beginning of this tutorial, we chose to use GitHub Actions as a CI provider. This created a basic CI pipeline and configured Nx Cloud in the repository. It also printed a URL in the terminal to register your repository in your [Nx Cloud](https://cloud.nx.app) account. If you didn't click on the link when first creating your repository, you can show it again by running:
If you are not able to connect via the automated process at [https://cloud.nx.app](https://cloud.nx.app), you can connect your workspace manually by running:
```shell ```shell
npx nx connect npx nx connect
``` ```
You will then need to merge your changes and connect to your workspace on [https://cloud.nx.app](https://cloud.nx.app). Once you click the link, follow the steps provided and make sure Nx Cloud is enabled on the main branch of your repository.
### Enable a Distributed CI Pipeline ### Configure Your CI Workflow
The current CI pipeline runs on a single machine and can only handle small workspaces. To transform your CI into a CI that runs on multiple machines and can handle workspaces of any size, uncomment the `npx nx-cloud start-ci-run` line in the `.github/workflows/ci.yml` file. When you chose GitHub Actions as your CI provider at the beginning of the tutorial, `create-nx-workspace` created a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR. Since we are using Nx Cloud, the pipeline will also distribute tasks across multiple machines to ensure fast and reliable CI runs.
```yml If you need to generate a new workflow file for GitHub Actions or other providers, you can do so with this command:
- run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
```shell
npx nx generate ci-workflow
``` ```
The key lines in the CI pipeline are:
```yml {% fileName=".github/workflows/ci.yml" highlightLines=["10-14", "21-22"] %}
name: CI
# ...
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# This enables task distribution via Nx Cloud
# Run this command as early as possible, before dependencies are installed
# Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
# Connect your workspace by running "nx connect" and uncomment this
- run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
- uses: actions/setup-node@v3
with:
node-version: 20
cache: 'npm'
- run: npm ci --legacy-peer-deps
- uses: nrwl/nx-set-shas@v4
# Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
- run: npx nx affected -t lint test build
```
### Open a Pull Request
Commit the changes and open a new PR on GitHub.
```shell
git add .
git commit -m 'add CI workflow file'
git push origin add-workflow
```
When you view the PR on GitHub, you will see a comment from Nx Cloud that reports on the status of the CI run.
![Nx Cloud report](/shared/tutorials/github-pr-cloud-report.avif)
The `See all runs` link goes to a page with the progress and results of tasks that were run in the CI pipeline.
![Run details](/shared/tutorials/nx-cloud-run-details.avif)
For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials: For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials:
- [Circle CI with Nx](/ci/intro/tutorials/circle) - [Circle CI with Nx](/ci/intro/tutorials/circle)

102
docs/shared/tutorials/react-standalone.md
View File

@ -980,53 +980,93 @@ This tutorial walked you through how Nx can improve the local development experi
- Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute. - Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute.
- Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks). - Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks).
### Generate a CI Workflow
If you are starting a new project, you can use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
{% callout type="note" title="Choose your CI provider" %}
You can choose `github`, `circleci`, `azure`, `bitbucket-pipelines`, or `gitlab` for the `ci` flag.
{% /callout %}
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR.
The key line in the CI pipeline is:
```yml
- run: npx nx affected -t lint test build e2e-ci
```
### Connect to Nx Cloud ### Connect to Nx Cloud
Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more. Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more.
To connect to Nx Cloud: Now that we're working on the CI pipeline, it is important for your changes to be pushed to a GitHub repository.
- Commit and push your changes 1. Commit your existing changes with `git add . && git commit -am "updates"`
- Go to [https://cloud.nx.app](https://cloud.nx.app), create an account, and connect your repository 2. [Create a new GitHub repository](https://github.com/new)
3. Follow GitHub's instructions to push your existing code to the repository
#### Connect to Nx Cloud Manually Now connect your repository to Nx Cloud with the following command:
If you are not able to connect via the automated process at [https://cloud.nx.app](https://cloud.nx.app), you can connect your workspace manually by running:
```shell ```shell
npx nx connect npx nx connect
``` ```
You will then need to merge your changes and connect to your workspace on [https://cloud.nx.app](https://cloud.nx.app). A browser window will open to register your repository in your [Nx Cloud](https://cloud.nx.app) account. The link is also printed to the terminal if the windows does not open, or you closed it before finishing the steps. The app will guide you to create a PR to enable Nx Cloud on your repository.
### Enable a Distributed CI Pipeline ![](/shared/tutorials/nx-cloud-github-connect.avif)
The current CI pipeline runs on a single machine and can only handle small workspaces. To transform your CI into a CI that runs on multiple machines and can handle workspaces of any size, uncomment the `npx nx-cloud start-ci-run` line in the `.github/workflows/ci.yml` file. Once the PR is created, merge it into your main branch.
```yml ![](/shared/tutorials/github-cloud-pr-merged.avif)
- run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
And make sure you pull the latest changes locally:
```shell
git pull
``` ```
You should now have an `nxCloudAccessToken` property specified in the `nx.json` file.
### Create a CI Workflow
Use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR. Since we are using Nx Cloud, the pipeline will also distribute tasks across multiple machines to ensure fast and reliable CI runs.
The key lines in the CI pipeline are:
```yml {% fileName=".github/workflows/ci.yml" highlightLines=["10-14", "21-22"] %}
name: CI
# ...
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# This enables task distribution via Nx Cloud
# Run this command as early as possible, before dependencies are installed
# Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
# Connect your workspace by running "nx connect" and uncomment this
- run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
- uses: actions/setup-node@v3
with:
node-version: 20
cache: 'npm'
- run: npm ci --legacy-peer-deps
- uses: nrwl/nx-set-shas@v4
# Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
- run: npx nx affected -t lint test build
```
### Open a Pull Request
Commit the changes and open a new PR on GitHub.
```shell
git add .
git commit -m 'add CI workflow file'
git push origin add-workflow
```
When you view the PR on GitHub, you will see a comment from Nx Cloud that reports on the status of the CI run.
![Nx Cloud report](/shared/tutorials/github-pr-cloud-report.avif)
The `See all runs` link goes to a page with the progress and results of tasks that were run in the CI pipeline.
![Run details](/shared/tutorials/nx-cloud-run-details.avif)
For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials: For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials:
- [Circle CI with Nx](/ci/intro/tutorials/circle) - [Circle CI with Nx](/ci/intro/tutorials/circle)

102
docs/shared/tutorials/vue-standalone.md
View File

@ -1036,53 +1036,93 @@ This tutorial walked you through how Nx can improve the local development experi
- Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute. - Nx Agents [efficiently distribute tasks across machines](/ci/concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute.
- Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks). - Nx Atomizer [automatically splits](/ci/features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/ci/features/flaky-tasks).
### Generate a CI Workflow
If you are starting a new project, you can use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
{% callout type="note" title="Choose your CI provider" %}
You can choose `github`, `circleci`, `azure`, `bitbucket-pipelines`, or `gitlab` for the `ci` flag.
{% /callout %}
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR.
The key line in the CI pipeline is:
```yml
- run: npx nx affected -t lint test build e2e-ci
```
### Connect to Nx Cloud ### Connect to Nx Cloud
Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more. Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more.
To connect to Nx Cloud: Now that we're working on the CI pipeline, it is important for your changes to be pushed to a GitHub repository.
- Commit and push your changes 1. Commit your existing changes with `git add . && git commit -am "updates"`
- Go to [https://cloud.nx.app](https://cloud.nx.app), create an account, and connect your repository 2. [Create a new GitHub repository](https://github.com/new)
3. Follow GitHub's instructions to push your existing code to the repository
#### Connect to Nx Cloud Manually Now connect your repository to Nx Cloud with the following command:
If you are not able to connect via the automated process at [https://cloud.nx.app](https://cloud.nx.app), you can connect your workspace manually by running:
```shell ```shell
npx nx connect npx nx connect
``` ```
You will then need to merge your changes and connect to your workspace on [https://cloud.nx.app](https://cloud.nx.app). A browser window will open to register your repository in your [Nx Cloud](https://cloud.nx.app) account. The link is also printed to the terminal if the windows does not open, or you closed it before finishing the steps. The app will guide you to create a PR to enable Nx Cloud on your repository.
### Enable a Distributed CI Pipeline ![](/shared/tutorials/nx-cloud-github-connect.avif)
The current CI pipeline runs on a single machine and can only handle small workspaces. To transform your CI into a CI that runs on multiple machines and can handle workspaces of any size, uncomment the `npx nx-cloud start-ci-run` line in the `.github/workflows/ci.yml` file. Once the PR is created, merge it into your main branch.
```yml ![](/shared/tutorials/github-cloud-pr-merged.avif)
- run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
And make sure you pull the latest changes locally:
```shell
git pull
``` ```
You should now have an `nxCloudAccessToken` property specified in the `nx.json` file.
### Create a CI Workflow
Use the following command to generate a CI workflow file.
```shell
npx nx generate ci-workflow --ci=github
```
This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR. Since we are using Nx Cloud, the pipeline will also distribute tasks across multiple machines to ensure fast and reliable CI runs.
The key lines in the CI pipeline are:
```yml {% fileName=".github/workflows/ci.yml" highlightLines=["10-14", "21-22"] %}
name: CI
# ...
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# This enables task distribution via Nx Cloud
# Run this command as early as possible, before dependencies are installed
# Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
# Connect your workspace by running "nx connect" and uncomment this
- run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
- uses: actions/setup-node@v3
with:
node-version: 20
cache: 'npm'
- run: npm ci --legacy-peer-deps
- uses: nrwl/nx-set-shas@v4
# Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
- run: npx nx affected -t lint test build
```
### Open a Pull Request
Commit the changes and open a new PR on GitHub.
```shell
git add .
git commit -m 'add CI workflow file'
git push origin add-workflow
```
When you view the PR on GitHub, you will see a comment from Nx Cloud that reports on the status of the CI run.
![Nx Cloud report](/shared/tutorials/github-pr-cloud-report.avif)
The `See all runs` link goes to a page with the progress and results of tasks that were run in the CI pipeline.
![Run details](/shared/tutorials/nx-cloud-run-details.avif)
For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials: For more information about how Nx can improve your CI pipeline, check out one of these detailed tutorials:
- [Circle CI with Nx](/ci/intro/tutorials/circle) - [Circle CI with Nx](/ci/intro/tutorials/circle)