From 9721844b053b2f0d12ede2bc9578e49b8c0fce1f Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Fri, 10 Jun 2022 22:22:49 -0400 Subject: [PATCH] Nx Cloud docs (#10690) * docs(nxdev): consume nx cloud documentation & dedicated menu * docs(nxdev): nx-cloud docs visually indicated nx-cloud docs in nx.dev * docs(nxdev): formatting visually indicated nx-cloud docs in nx.dev * docs(nxdev): fix config * docs(nxdev): fix header link * docs(nxdev): consolidate dte set up guides Co-authored-by: ben <3447705+bcabanes@users.noreply.github.com> --- docs/map.json | 12 +- docs/nx-cloud/intro/distributed-caching.md | 37 --- .../intro/distributed-task-execution.md | 38 --- docs/nx-cloud/intro/nx-cloud.md | 18 +- docs/nx-cloud/private/auth-github.md | 4 +- docs/nx-cloud/private/auth-gitlab.md | 2 +- docs/nx-cloud/private/auth-single-admin.md | 14 +- docs/nx-cloud/private/get-started.md | 12 +- docs/nx-cloud/private/github.md | 10 +- docs/nx-cloud/reference/release-notes.md | 2 +- docs/nx-cloud/reference/server-api.md | 2 +- docs/nx-cloud/set-up/github.md | 4 +- docs/nx-cloud/set-up/set-up-dte.md | 260 +----------------- docs/shared/distributed-builds.md | 2 +- docs/shared/monorepo-ci-azure.md | 6 +- .../shared/monorepo-ci-bitbucket-pipelines.md | 6 +- docs/shared/monorepo-ci-circle-ci.md | 6 +- docs/shared/monorepo-ci-github-actions.md | 8 +- docs/shared/monorepo-ci-gitlab.md | 6 +- docs/shared/monorepo-ci-jenkins.md | 6 +- .../shared/nx-cloud-logo-horizontal-white.svg | 11 + docs/shared/using-nx/caching.md | 30 ++ docs/shared/using-nx/dte.md | 4 + nx-dev/data-access-menu/src/lib/menu.api.ts | 33 ++- nx-dev/data-access-menu/src/lib/menu.utils.ts | 35 +++ nx-dev/feature-doc-viewer/src/lib/content.tsx | 2 + .../nx-cloud-documentation.spec.ts | 103 +++++++ nx-dev/nx-dev/lib/api.ts | 23 +- nx-dev/nx-dev/pages/[...segments].tsx | 21 +- nx-dev/nx-dev/styles/main.css | 26 ++ nx-dev/ui-common/src/lib/header.tsx | 13 +- nx-dev/ui-common/src/lib/sidebar.tsx | 9 +- package.json | 1 + yarn.lock | 208 ++++++++++++++ 34 files changed, 573 insertions(+), 401 deletions(-) delete mode 100644 docs/nx-cloud/intro/distributed-caching.md delete mode 100644 docs/nx-cloud/intro/distributed-task-execution.md create mode 100644 docs/shared/nx-cloud-logo-horizontal-white.svg create mode 100644 nx-dev/nx-dev-e2e/src/integration/nx-cloud-documentation.spec.ts diff --git a/docs/map.json b/docs/map.json index 21e8d42d06290..48c250190b46b 100644 --- a/docs/map.json +++ b/docs/map.json @@ -701,18 +701,8 @@ "itemList": [ { "name": "What is Nx Cloud?", - "id": "nx-cloud", + "id": "what-is-nx-cloud", "file": "nx-cloud/intro/nx-cloud" - }, - { - "name": "Distributed Caching", - "id": "distributed-caching", - "file": "nx-cloud/intro/distributed-caching" - }, - { - "name": "Distributed Task Execution", - "id": "distributed-task-execution", - "file": "nx-cloud/intro/distributed-task-execution" } ] }, diff --git a/docs/nx-cloud/intro/distributed-caching.md b/docs/nx-cloud/intro/distributed-caching.md deleted file mode 100644 index d024ab5066fc7..0000000000000 --- a/docs/nx-cloud/intro/distributed-caching.md +++ /dev/null @@ -1,37 +0,0 @@ -# Distributed Caching - -## Only Build, Test, Lint Once - -...across your entire organization. - -When running Nx without Nx Cloud, a [computation cache is created on your local machine](https://nx.dev/using-nx/caching) to make the developer experience faster. This allows you to not waste time re-building, re-testing, re-linting, or any number of other actions you might take on code that hasn’t changed. Since the cache is stored locally, you are the only member of your team that can take advantage of these instant commands. - -Nx Cloud allows this cache to be shared across your entire organization, meaning that any cacheable operation completed on your workspace only needs to be run once. - -The time savings that this can provide your team are drastic. [This blog post](https://blog.nrwl.io/how-to-never-build-or-test-the-same-code-twice-2dc58e413279) explains how such a simple concept can have a massive impact on productive time for you and your team. - -## Caching Priority - -Whenever you run a cacheable command with Nx, Nx attempts to fulfill that command using the first successful strategy in the following list: - -1. Check the local cache. If the command is cached there, replay the cached output. -2. Check the Nx Cloud distributed cache. If the command is cached there, store the cache locally and replay the cached output. -3. Run the command locally. Store the output in local cache. If you have a read-write access token, store the output in the Nx Cloud distributed cache. - -This algorithm optimizes for speed locally and minimizes unnecessary use of the distributed cache. - -## When is a Distributed Cache Helpful? - -Generally speaking, the bigger the organization, the more helpful a distributed cache becomes. However, distributed cache is still useful even in the following scenarios with two developers and a CI/CD machine. - -### Scenario 1: Help Me Fix This Bug - -Perry works on a feature, but he can't figure out why it isn't working the way he expects. Neelam checks out that branch to help. Neelam doesn't need to re-run all the tests that Perry already ran. - -### Scenario 2: Why Is This Breaking in CI? - -Tony pushes a branch up to CI, but CI doesn't pass. He asks Sofija to help. Sofija checks out that branch to troubleshoot. Sofija can reuse the output from CI instead of waiting for builds to run on her machine. - -### Scenario 3: CI Should Know It Already Did That - -Maya and Trey push up changes to two different apps that both depend on an unchanged shared buildable library. CI reuses the build output of the shared buildable library when building the apps in the two different PRs. diff --git a/docs/nx-cloud/intro/distributed-task-execution.md b/docs/nx-cloud/intro/distributed-task-execution.md deleted file mode 100644 index 11134eea70505..0000000000000 --- a/docs/nx-cloud/intro/distributed-task-execution.md +++ /dev/null @@ -1,38 +0,0 @@ -# Distributed Task Execution - -> Before reading this guide, check out the [mental model guide](/using-nx/mental-model). It will help you understand how computation caching fits into the rest of Nx. - -## Overview - -Nx supports running commands across multiple machines. You can either set it up by hand ( -see [here](/ci/distributed-builds)) or use Nx Cloud. - -[Read the comparison of the two approaches.](https://blog.nrwl.io/distributing-ci-binning-and-distributed-task-execution-632fe31a8953?source=friends_link&sk=5120b7ff982730854ed22becfe7a640a) - -When using the distributed task execution, Nx is able to run any task graph on many agents instead of locally. - -For instance, `nx affected --build` won't run the build locally (which can take hours for large workspaces). Instead, -it will send the Task Graph to Nx Cloud. Nx Cloud Agents will then pick up the tasks they can run and execute them. - -Note that this happens transparently. If an agent builds `app1`, it will fetch the outputs for `lib` if it doesn't have them -already. - -As agents complete tasks, the main job where you invoked `nx affected --build` will start receiving created files and -terminal outputs. - -After `nx affected --build` completes, the machine will have the build files and all the terminal outputs as if it ran -it locally. - -![DTE](/shared/mental-model/dte.png) - -## Set Up - -To set up your workspace for distributed task execution [follow this guide](/nx-cloud/set-up/set-up-dte). - -## Example - -[This is an example repo](https://github.com/vsavkin/interstellar) showing how easy it is to set up distributed task execution, showing the performance gains, and comparing to sharding/binning. - -These are the savings you get by enabling Distributed Task Execution in your CI config: - -![DTE](/shared/using-nx/dte.png) diff --git a/docs/nx-cloud/intro/nx-cloud.md b/docs/nx-cloud/intro/nx-cloud.md index 2d8260db7f652..463785c882ce6 100644 --- a/docs/nx-cloud/intro/nx-cloud.md +++ b/docs/nx-cloud/intro/nx-cloud.md @@ -1,21 +1,21 @@ -# Nx Cloud +# What is Nx Cloud? -## Save Time With Distributed Task Execution & Cache +## Save Time With Distributed Task Execution & Distributed Cache -Nx partitions a command into smaller tasks and runs them in parallel, in the correct order. Nx Cloud takes it one step further and [runs any command across multiple machines](/nx-cloud/intro/distributed-task-execution), while giving you a consolidated view of the command as if it ran locally. +Nx partitions a command into smaller tasks and runs them in parallel, in the correct order. Nx Cloud takes it one step further and [runs any command across multiple machines](/using-nx/dte), while giving you a consolidated view of the command as if it ran locally. -Nx caches the output of any previously run command such as testing and building, so it can replay the cached results instead of rerunning it. Nx Cloud allows you to [share the computation cache](/nx-cloud/intro/distributed-caching) across everyone in your team and CI. +Nx caches the output of any previously run command such as testing and building, so it can replay the cached results instead of rerunning it. Nx Cloud allows you to [share the computation cache](/using-nx/caching#distributed-computation-caching) across everyone in your team and CI. -No configuration needed. +And it takes five minutes to set up. ## Clean User Interface Most developers will benefit from Nx Cloud without ever changing any of their workflow. Commands will just execute faster. For those developers that are tasked with making the most of Nx Cloud or those that want to get more insight into the different commands executed in the repository, Nx Cloud has a clean, informative user interface. -The top level organization page displays recent runs and a helpful dashboard of information about commands run in the repository. +The [top level organization page](https://nx.app/orgs/5e38af6de037b5000598b2d6/workspaces/5edaf12087863a0005781f17) displays recent runs and a helpful dashboard of information about commands run in the repository. - -Each branch in the repository has its own dedicated page where you can view agent utilization and a waterfall task execution graph for the most recent runs against that branch. +Each branch in the repository has its own [dedicated page](https://nx.app/branch?workspaceId=5edaf12087863a0005781f17&branchName=master) where you can view agent utilization and a waterfall task execution graph for the most recent runs against that branch. - diff --git a/docs/nx-cloud/private/auth-github.md b/docs/nx-cloud/private/auth-github.md index 4fcea5ab47cfb..fc9470086674e 100644 --- a/docs/nx-cloud/private/auth-github.md +++ b/docs/nx-cloud/private/auth-github.md @@ -36,7 +36,7 @@ And then generate a new client secret, and save it somewhere secure (we'll use i ## Connect your private cloud instance to your OAuth App -[When setting up your private cloud](https://nx.app/docs/get-started-with-private-cloud-community), you can pass these two environment variables to it: +[When setting up your private cloud](/nx-cloud/private-cloud/get-started), you can pass these two environment variables to it: ```bash GITHUB_AUTH_CLIENT_ID=... @@ -53,4 +53,4 @@ If you are running an on-premise version of GitHub (Enterprise Server), you will This will point all auth endpoints to your GitHub server (rather the public one). -Note: the above environment variable, also helps with setting up the GitHub app integration, so you can have NxCloud build stats directly on your pull request. See full set-up instructions [here](https://nx.app/docs/private-cloud-github-integration). +Note: the above environment variable, also helps with setting up the GitHub app integration, so you can have NxCloud build stats directly on your pull request. See full set-up instructions [here](/nx-cloud/private-cloud/github). diff --git a/docs/nx-cloud/private/auth-gitlab.md b/docs/nx-cloud/private/auth-gitlab.md index c2b304b4a38f9..8b04925466401 100644 --- a/docs/nx-cloud/private/auth-gitlab.md +++ b/docs/nx-cloud/private/auth-gitlab.md @@ -32,7 +32,7 @@ Once you create, keep a note of the Client ID and the Secret: ## Connect your private cloud instance to your new app -[When setting up your private cloud](https://nx.app/docs/get-started-with-private-cloud-community), you can pass these two environment variables to it: +[When setting up your private cloud](/nx-cloud/private-cloud/get-started), you can pass these two environment variables to it: ```bash GITLAB_APP_ID=... diff --git a/docs/nx-cloud/private/auth-single-admin.md b/docs/nx-cloud/private/auth-single-admin.md index f6e4b5cf25d9e..0c2dbe607233a 100644 --- a/docs/nx-cloud/private/auth-single-admin.md +++ b/docs/nx-cloud/private/auth-single-admin.md @@ -3,20 +3,20 @@ There are a few methods of authenticating users in Nx Private Cloud: - single-admin user -- [GitHub OAuth2](https://nx.app/docs/private-cloud-github-auth) -- [GitLab OAuth2](https://nx.app/docs/private-cloud-gitlab-auth) +- [GitHub OAuth2](/nx-cloud/private-cloud/auth-github) +- [GitLab OAuth2](/nx-cloud/private-cloud/auth-gitlab) ## Why do users need access While just adding an NxCloud access token to your monorepo give you distributed caching, the NxCloud web app gives you analytics about tasks running in your workspace, allows devs to easily inspect terminal output, and works seamlessly with our GitHub integration for your Pull Requests. Here is a [video walkthrough of this](https://youtu.be/GT7XIwG1i5A?t=409). -By default, when you connect your token to a workspace on your NxCloud web app, all links and runs are private to only members of your organisation. This means that you'll either need to explicitly add members, or make your organisation public (which means anyone with access to your Private NxCloud instance will be able to see your runs). [More details here.](https://nx.app/docs/manage-access#accessing-nx-cloud) +By default, when you connect your token to a workspace on your NxCloud web app, all links and runs are private to only members of your organisation. This means that you'll either need to explicitly add members, or make your organisation public (which means anyone with access to your Private NxCloud instance will be able to see your runs). [More details here.](/nx-cloud/account/users#managing-members) ## Setting up a single admin user -If you just want to try out private cloud and set-up full membership management later, then the simplest option is to just set-up a single admin user. This option might also work for you if you are okay with [making your organisation public](https://nx.app/docs/manage-access#accessing-nx-cloud) to anyone that has access to your private cloud NxCloud instance. +If you just want to try out private cloud and set-up full membership management later, then the simplest option is to just set-up a single admin user. This option might also work for you if you are okay with [making your organisation public](/nx-cloud/account/users#public-organizations) to anyone that has access to your private cloud NxCloud instance. -[While setting up your container](https://nx.app/docs/get-started-with-private-cloud-community) you can pass it the `ADMIN_PASSWORD` environment variable. This will set-up a default admin user for you, which you can use to manage your workspace on the NxCloud web app. +[While setting up your container](/nx-cloud/private-cloud/get-started) you can pass it the `ADMIN_PASSWORD` environment variable. This will set-up a default admin user for you, which you can use to manage your workspace on the NxCloud web app. Note: Even if you can make your organisation public, we still recommend setting up GitHub authentication and inviting more than 1 admin to your workspace, to reduce the chance of losing access to it. @@ -24,8 +24,8 @@ Note: Even if you can make your organisation public, we still recommend setting For instructions on how to set-up third-party auth providers please refer to these guides: -- [GitHub Auth](https://nx.app/docs/private-cloud-github-auth) -- [GitLab Auth](https://nx.app/docs/private-cloud-gitlab-auth) +- [GitHub Auth](/nx-cloud/private-cloud/auth-github) +- [GitLab Auth](/nx-cloud/private-cloud/auth-gitlab) ## Inviting users diff --git a/docs/nx-cloud/private/get-started.md b/docs/nx-cloud/private/get-started.md index b5f8f44872e6c..c951c3ecda700 100644 --- a/docs/nx-cloud/private/get-started.md +++ b/docs/nx-cloud/private/get-started.md @@ -2,7 +2,7 @@ Nx Private Cloud is a docker image that can be deployed to your cloud. This version keeps all data on your cloud, except for billing and utilization data that's sent to the Nx Cloud API to enable an integrated billing experience. -For companies who need complete control of data, with no external API calls, the [Nx Enterprise](https://nx.app/docs/get-started-with-private-cloud-enterprise) is for you. +For companies who need complete control of data, with no external API calls, the [Nx Enterprise](/nx-cloud/private-cloud/get-started) is for you. **Nx Cloud consists of 3 parts:** @@ -16,7 +16,7 @@ When running everything together, you won't be able to run more than one instanc The instructions will go through running everything together first, and then, at the end, will talk about running the database and the file server separately. -The instructions will use Docker commands, but you can also deploy Nx Cloud to a Kubernetes cluster (see [here](https://nx.app/docs/kubernetes) for more information). +The instructions will use Docker commands, but you can also deploy Nx Cloud to a Kubernetes cluster (see [here](/nx-cloud/private-cloud/deploy-kubernetes) for more information). ## Running Nx Private Cloud @@ -83,7 +83,7 @@ Depending on how your infrastructure is set up, you can either run Nx Private Cl - `443:8081` maps the internal port 8081 to 443, so it can be accessed in the browser without specifying the port. 80:8081 works the same way when you use HTTP instead of HTTPS. - `CERT_KEY` and `CERT` contain the values of private key and cert. The file extensions of the cert and key files can be different, but as long as they are in the PEM format (which is the case if you use, for instance, OpenSSL), the command will work. - `NX_CLOUD_APP_URL` is the URL the cloud can be accessed by (e.g., `https://nxcloud.privateurl.com`). **Important: Unless you are experimenting, it won't be localhost. It has to be the URL that your CI and your developer machine can reach. Also note, there is no trailing slash in the URL.** -- `ADMIN_PASSWORD` contains the password of the admin user. The admin user is created the first time you run cloud, you can remove this env variable after that. Instead of an admin password, you can also follow [the instructions here](https://nx.app/docs/private-cloud-github-auth) to set-up GitHub auth. +- `ADMIN_PASSWORD` contains the password of the admin user. The admin user is created the first time you run cloud, you can remove this env variable after that. Instead of an admin password, you can also follow [the instructions here](/nx-cloud/private-cloud/auth-github) to set-up GitHub auth. - `-v /data/private-cloud:/data` sets up the volume where the data is stored. `/data/private-cloud` refers to a folder on your machine, `/data` is the shareable folder from the Docker image. ### Step 3: Run the Container @@ -112,11 +112,11 @@ As stated above, Nx Private Cloud will store all your artifacts and the informat ### Optional step 6: Set-up GitHub auth -Follow the [instructions here](https://nx.app/docs/private-cloud-github-auth) to set-up GitHub OAuth authentication so you can invite other members in your team to the workspace. +Follow the [instructions here](/nx-cloud/private-cloud/auth-github) to set-up GitHub OAuth authentication so you can invite other members in your team to the workspace. ### Optional step 7: Set-up GitHub Pull Request integration -You can [optionally configure private cloud](https://nx.app/docs/private-cloud-github-integration) to post build stats directly on your GitHub pull requests. +You can [optionally configure private cloud](/nx-cloud/private-cloud/github) to post build stats directly on your GitHub pull requests. ### Optional step 8: Setting Up Proxy @@ -138,7 +138,7 @@ By default, Nx Cloud requires Mongo 4.2+. If you are using an older version of M ### Using MongoDB Kubernetes Operator -The MongoDB team maintains the open source [MongoDB Kubernetes Operator](https://github.com/mongodb/mongodb-kubernetes-operator). You can use it to set up your own deployment of MongoDB. See [the Nx Cloud and Kubernetes page](https://nx.app/docs/kubernetes) for more information. +The MongoDB team maintains the open source [MongoDB Kubernetes Operator](https://github.com/mongodb/mongodb-kubernetes-operator). You can use it to set up your own deployment of MongoDB. See [the Nx Cloud and Kubernetes page](/nx-cloud/private-cloud/deploy-kubernetes) for more information. ### Using CosmosDB diff --git a/docs/nx-cloud/private/github.md b/docs/nx-cloud/private/github.md index 2583835ce26eb..8777a124d5926 100644 --- a/docs/nx-cloud/private/github.md +++ b/docs/nx-cloud/private/github.md @@ -1,4 +1,4 @@ -# Private Cloud GitHub Integration +# Private Cloud GitHub PR Integration ## Set Up a Webhook @@ -7,12 +7,12 @@ - Content type: `application/json` - Add a "Secret" (can be anything). Remember it, as we'll need to pass it to our Docker container. -![Add webhook to github](/nx-cloud/private/private-cloud-github-integration-add-webhook.png) +![Add webhook to github](/nx-cloud/private/images/private-cloud-github-integration-add-webhook.png) - Enable "Check Suites", "Check runs" and "Pull Requests" as the events that trigger the webhook. -![Enable check suites and check runs](/nx-cloud/private/webhook-trigger-events.png) -![Enable pull requests](/nx-cloud/private/webhook-trigger-pull-requests.png) +![Enable check suites and check runs](/nx-cloud/private/images/webhook-trigger-events.png) +![Enable pull requests](/nx-cloud/private/images/webhook-trigger-pull-requests.png) ## Generate Access token @@ -21,7 +21,7 @@ - Make sure you select "repo" as a scope - After you generate the token, make sure to copy and store it. We'll add it to Private Cloud in a bit. -![Generate personal access token](/nx-cloud/private/private-cloud-github-integration-generate-tokens.png) +![Generate personal access token](/nx-cloud/private/images/private-cloud-github-integration-generate-token.png) ## Optional - Configure Self-Hosted GitHub Instances diff --git a/docs/nx-cloud/reference/release-notes.md b/docs/nx-cloud/reference/release-notes.md index 333fc9474ac16..387244b7be041 100644 --- a/docs/nx-cloud/reference/release-notes.md +++ b/docs/nx-cloud/reference/release-notes.md @@ -2,7 +2,7 @@ ## 13.3.1 -- Feat: Store output for non-Nx commands in Nx Cloud. Check out https://nx.app/docs/record-non-nx-commands for more information. +- Feat: Store output for non-Nx commands in Nx Cloud. Check out https://nx.dev/nx-cloud/set-up/record-commands for more information. ## 13.2.1 diff --git a/docs/nx-cloud/reference/server-api.md b/docs/nx-cloud/reference/server-api.md index 7de5cf5dc2149..8f99fe2423c84 100644 --- a/docs/nx-cloud/reference/server-api.md +++ b/docs/nx-cloud/reference/server-api.md @@ -1,4 +1,4 @@ -# Nx API Spec +# Nx Cloud Server API Reference ## OpenAPI 3.0.3 diff --git a/docs/nx-cloud/set-up/github.md b/docs/nx-cloud/set-up/github.md index 56d9dc357d550..b86388d5666b9 100644 --- a/docs/nx-cloud/set-up/github.md +++ b/docs/nx-cloud/set-up/github.md @@ -1,4 +1,4 @@ -# Github Integration +# Enable Github PR Integration ## Get Started @@ -6,7 +6,7 @@ The [Nx Cloud Github App](https://github.com/marketplace/official-nx-cloud-app) ## Nx Public Cloud CI Setup -Before you install the app, please make sure you have a **valid Nx Cloud `accessToken` in your `nx.json` file**. Nx Cloud reports will not generate properly on your PRs without one. You should already have one if you’re using Nx Cloud, but if you don’t, you can learn how to add one [here](https://nx.app/docs/manage-access). +Before you install the app, please make sure you have a **valid Nx Cloud `accessToken` in your `nx.json` file**. Nx Cloud reports will not generate properly on your PRs without one. You should already have one if you’re using Nx Cloud, but if you don’t, you can learn how to add one [here](/nx-cloud/account/users). You can find and install the app from [the GitHub marketplace](https://github.com/marketplace/official-nx-cloud-app). diff --git a/docs/nx-cloud/set-up/set-up-dte.md b/docs/nx-cloud/set-up/set-up-dte.md index cff7acd6b7dfd..b945c4e995ac0 100644 --- a/docs/nx-cloud/set-up/set-up-dte.md +++ b/docs/nx-cloud/set-up/set-up-dte.md @@ -1,4 +1,4 @@ -# Set up Distributed Task Execution +# Set Up Distributed Task Execution To enable distributed task execution, the following has to be true: @@ -34,7 +34,7 @@ Setting `NX_CLOUD_DISTRIBUTED_EXECUTION_STOP_AGENTS_ON_FAILURE` to false will te ## Distributed Task Execution and Sharding -The Nx Cloud distributed task execution model is akin to what is used at Google or Facebook. It scales better and provided more flexiblity than sharding tasks across agents. [Read more about Distributed Task Execution and how it compares to binning/sharding.](https://blog.nrwl.io/distributing-ci-binning-and-distributed-task-execution-632fe31a8953?source=friends_link&sk=5120b7ff982730854ed22becfe7a640a) +The Nx Cloud distributed task execution model is akin to what is used at Google or Facebook. It scales better and provided more flexibility than sharding tasks across agents. [Read more about Distributed Task Execution and how it compares to binning/sharding.](https://blog.nrwl.io/distributing-ci-binning-and-distributed-task-execution-632fe31a8953?source=friends_link&sk=5120b7ff982730854ed22becfe7a640a) ## CI/CD Examples @@ -44,258 +44,10 @@ Every organization manages their CI/CD pipelines differently, so the examples do Read the guides for more information on how to configure them in CI. -### GitHub Actions - -An example of a GitHub Actions setup for an Nx workspace connected to Nx Cloud. - -```yml -name: CI -on: - push: - branches: - - main - pull_request: - -env: - NX_CLOUD_DISTRIBUTED_EXECUTION: true - -jobs: - main: - runs-on: ubuntu-latest - if: ${{ github.event_name != 'pull_request' }} - steps: - - uses: actions/checkout@v2 - name: Checkout [main] - with: - fetch-depth: 0 - - name: Derive appropriate SHAs for base and head for `nx affected` commands - uses: nrwl/nx-set-shas@v2 - - uses: actions/setup-node@v1 - with: - node-version: '14' - - run: npm install - - run: npx nx-cloud start-ci-run - - run: npx nx affected --target=build --parallel --max-parallel=3 - - run: npx nx affected --target=test --parallel --max-parallel=2 - - run: npx nx-cloud stop-all-agents - pr: - runs-on: ubuntu-latest - if: ${{ github.event_name == 'pull_request' }} - steps: - - uses: actions/checkout@v2 - with: - ref: ${{ github.event.pull_request.head.ref }} - fetch-depth: 0 - - name: Derive appropriate SHAs for base and head for `nx affected` commands - uses: nrwl/nx-set-shas@v2 - - uses: actions/setup-node@v1 - with: - node-version: '14' - - run: npm install - - run: npx nx-cloud start-ci-run - - run: npx nx affected --target=build --parallel --max-parallel=3 - - run: npx nx affected --target=test --parallel --max-parallel=2 - - run: npx nx-cloud stop-all-agents - agents: - runs-on: ubuntu-latest - name: Agent 1 - timeout-minutes: 60 - strategy: - matrix: - agent: [1, 2, 3] - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v1 - with: - node-version: '14' - - run: npm install - - name: Start Nx Agent ${{ matrix.agent }} - run: npx nx-cloud start-agent -``` - -The `pr` and `main` jobs implement the CI workflow. The 3 agent jobs execute the tasks created by `pr` and `main`. Setting timeout-minutes is needed only if you have very slow tasks. - -Note that if you use an older version of `@nrwl/nx-cloud`, you need to add the following two env variables. - -```yml -env: - NX_BRANCH: ${{ github.head_ref }} - NX_RUN_GROUP: ${{ github.run_id }} -``` - -You can find more information about using GitHub Actions on the [`nx-tag-successful-ci-run`](https://github.com/nrwl/nx-tag-successful-ci-run) and [`nx-set-shas`](https://github.com/nrwl/nx-set-shas) repos. - -### Circle CI - -An example of a Circle CI setup for an Nx workspace connected to Nx Cloud. - -```yml -version: 2.1 -orbs: - nx: nrwl/nx@1.0.0 -jobs: - agent: - steps: - - checkout - - run: npm install - - run: - command: npx nx-cloud start-agent - no_output_timeout: 60m - main: - environment: - NX_CLOUD_DISTRIBUTED_EXECUTION: 'true' - steps: - - checkout - - run: npm install - - nx/set-shas - - run: npx nx affected --base=$NX_BASE --target=build --parallel --max-parallel=3 - - run: npx nx affected --base=$NX_BASE --target=test --parallel --max-parallel=2 - - run: npx nx-cloud stop-all-agents - pr: - environment: - NX_CLOUD_DISTRIBUTED_EXECUTION: 'true' - steps: - - checkout - - run: npm install - - nx/set-shas - - run: npx nx affected --base=$NX_BASE --target=build --parallel --max-parallel=3 - - run: npx nx affected --base=$NX_BASE --target=test --parallel --max-parallel=2 - - run: npx nx-cloud stop-all-agents -workflows: - build: - jobs: - - agent: - name: 'agent1' - - agent: - name: 'agent2' - - agent: - name: 'agent3' - - main: - filters: - branches: - only: main - - pr: - filters: - branches: - ignore: main -``` - -The `pr` and `main` jobs implement the CI workflow. The 3 agent jobs execute the tasks created by `pr` and `main`. Setting `no_output_timeout` is needed only if you have very slow tasks. - -## Azure Pipelines - -Unlike GitHub actions and CircleCI, we don't have the accordance to help you track the last successful run on `main`. In the example below, the base is set to `HEAD~1`, but a more robust solution would be to tag a SHA in the main job once it succeeds, and then use this tag as a base. See the [`nx-tag-successful-ci-run`](https://github.com/nrwl/nx-tag-successful-ci-run) and [`nx-set-shas`](https://github.com/nrwl/nx-set-shas) repos for more information. - -We also have to set `NX_BRANCH` explicitly. - -```yml -trigger: - - main -pr: - - main - -variables: - NX_CLOUD_DISTRIBUTED_EXECUTION: 'true' - ${{ if eq(variables['Build.SourceBranchName'], 'main') }}: - NX_BRANCH: 'main' - ${{ if ne(variables['Build.SourceBranchName'], 'main') }}: - NX_BRANCH: $(System.PullRequest.PullRequestNumber) - -jobs: - - job: agent - pool: - vmImage: 'ubuntu-latest' - strategy: - parallel: 4 - steps: - - script: npm i - - script: pnpx nx-cloud start-agent - - - job: main - pool: - vmImage: 'ubuntu-latest' - condition: ne(variables['Build.Reason'], 'PullRequest')) - steps: - - script: npm i - - script: npx nx-cloud start-ci-run - - script: npx nx affected --base=HEAD~1 --target=build --parallel --max-parallel=3 - - script: npx nx affected --base=HEAD~1 --target=test --parallel --max-parallel=2 - - script: npx nx-cloud stop-all-agents - - - job: pr - pool: - vmImage: 'ubuntu-latest' - condition: eq(variables['Build.Reason'], 'PullRequest')) - steps: - - script: npm i - - script: npx nx-cloud start-ci-run - - script: npx nx affected --target=build --parallel --max-parallel=3 - - script: npx nx affected --target=test --parallel --max-parallel=2 - - script: npx nx-cloud stop-all-agents -``` - -## Jenkins - -Unlike GitHub actions and CircleCI, we don't have the accordance to help you track the last successful run on `main`. In the example below, the base is set to `HEAD~1`, but a more robust solution would be to tag a SHA in the main job once it succeeds, and then use this tag as a base. - -We also have to set `NX_BRANCH` explicitly. - -```yml -pipeline { -agent none -environment { -NX_CLOUD_DISTRIBUTED_EXECUTION = 'true' -NX_BRANCH = env.BRANCH_NAME.replace('PR-', '') -NX_RUN_GROUP = env.BUILD_ID // has to be unique -} -stages { -stage('Pipeline') { -parallel { -stage('Agent') { -matrix { -agent any -axes { -axis { -name 'Number' -values '1', '2', '3' -} -} -steps { -sh "npm install" -sh "npx nx-cloud start" -} -} -} -stage('Main') { -when { -branch 'main' -} -agent any -steps { -sh "npm install" -sh "npx nx-cloud start-ci-run" -sh "npx nx affected --base=HEAD~1 --target=build --parallel --max-parallel=3" -sh "npx nx affected --base=HEAD~1 --target=test --parallel --max-parallel=2" -sh "npx nx-cloud stop-all-agents" -} -} -stage('PR') { -when { -not { branch 'main' } -} -agent any -steps { -sh "npm install" -sh "npx nx-cloud start-ci-run" -sh "npx nx affected --target=build --parallel --max-parallel=3" -sh "npx nx affected --target=test --parallel --max-parallel=2" -sh "npx nx-cloud stop-all-agents" -} -} -} -} -} -``` +- [Azure Pipelines](/ci/monorepo-ci-azure#distributed-ci-with-nx-cloud) +- [Circle CI](/ci/monorepo-ci-circle-ci#distributed-ci-with-nx-cloud) +- [GitHub Actions](/ci/monorepo-ci-github-actions#distributed-ci-with-nx-cloud) +- [Jenkins](/ci/monorepo-ci-jenkins#distributed-ci-with-nx-cloud) ## Additional Notes diff --git a/docs/shared/distributed-builds.md b/docs/shared/distributed-builds.md index fa836afdf5660..6120edb943a5d 100644 --- a/docs/shared/distributed-builds.md +++ b/docs/shared/distributed-builds.md @@ -6,7 +6,7 @@ But regardless of how smart Nx is, there will be some large changes affecting th There are several ways to distribute your CI across multiple machines. -The easiest way is to use Nx Cloud. Learn more about [configuring your CI](https://nx.app/docs/configuring-ci) environment using Nx Cloud with [Distributed Caching](https://nx.app/docs/distributed-caching) and [Distributed Task Execution](https://nx.app/docs/distributed-execution) in the Nx Cloud docs. +The easiest way is to use Nx Cloud. Learn more about [configuring your CI](/nx-cloud/set-up/set-up-dte#cicd-examples) environment using Nx Cloud with [Distributed Caching](/nx-cloud/set-up/set-up-caching) and [Distributed Task Execution](/nx-cloud/set-up/set-up-dte) in the Nx Cloud docs. But you can also set up distribution manually using the `print-affected` and `run-many` commands. diff --git a/docs/shared/monorepo-ci-azure.md b/docs/shared/monorepo-ci-azure.md index fca8c4fe68a1f..218eeb03f7ad1 100644 --- a/docs/shared/monorepo-ci-azure.md +++ b/docs/shared/monorepo-ci-azure.md @@ -54,6 +54,8 @@ jobs: The `main` job implements the CI workflow. +
+ ## Distributed CI with Nx Cloud A computation cache is created on your local machine to make the developer experience faster. This allows you to not waste time re-building, re-testing, re-linting, or any number of other actions you might take on code that hasn't changed. Because the cache is stored locally, you are the only member of your team that can take advantage of these instant commands. You can manage and share this cache manually. @@ -111,4 +113,6 @@ jobs: You can also use our [ci-workflow generator](https://nx.dev/packages/workspace/generators/ci-workflow) to generate the pipeline file. -Learn more about [configuring your CI](https://nx.app/docs/configuring-ci) environment using Nx Cloud with [Distributed Caching](https://nx.app/docs/distributed-caching) and [Distributed Task Execution](https://nx.app/docs/distributed-execution) in the Nx Cloud docs. +Learn more about configuring your CI environment using Nx Cloud with [Distributed Caching](/nx-cloud/set-up/set-up-caching) and [Distributed Task Execution](/nx-cloud/set-up/set-up-dte) in the Nx Cloud docs. + +
diff --git a/docs/shared/monorepo-ci-bitbucket-pipelines.md b/docs/shared/monorepo-ci-bitbucket-pipelines.md index ad04f3e2c48e8..fa432c0836e90 100644 --- a/docs/shared/monorepo-ci-bitbucket-pipelines.md +++ b/docs/shared/monorepo-ci-bitbucket-pipelines.md @@ -50,10 +50,14 @@ pipelines: The `pull-requests` and `main` jobs implement the CI workflow. +
+ ## Distributed CI with Nx Cloud A computation cache is created on your local machine to make the developer experience faster. This allows you to not waste time re-building, re-testing, re-linting, or any number of other actions you might take on code that hasn't changed. Because the cache is stored locally, you are the only member of your team that can take advantage of these instant commands. You can manage and share this cache manually. Nx Cloud allows this cache to be shared across your entire organization, meaning that any cacheable operation completed on your workspace only needs to be run once. Nx Cloud also allows you to distribute your CI across multiple machines to make sure the CI is fast even for very large repos. -Learn more about [configuring your CI](https://nx.app/docs/configuring-ci) environment using Nx Cloud with [Distributed Caching](https://nx.app/docs/distributed-caching) and [Distributed Task Execution](https://nx.app/docs/distributed-execution) in the Nx Cloud docs. +Learn more about configuring your CI environment using Nx Cloud with [Distributed Caching](/nx-cloud/set-up/set-up-caching) and [Distributed Task Execution](/nx-cloud/set-up/set-up-dte) in the Nx Cloud docs. + +
diff --git a/docs/shared/monorepo-ci-circle-ci.md b/docs/shared/monorepo-ci-circle-ci.md index c2927a7d36f2c..2a692960fd56f 100644 --- a/docs/shared/monorepo-ci-circle-ci.md +++ b/docs/shared/monorepo-ci-circle-ci.md @@ -51,6 +51,8 @@ To use the [Nx Orb](https://github.com/nrwl/nx-orb) with a private repository on > Note: It should be a user token, not project token. +
+ ## Distributed CI with Nx Cloud A computation cache is created on your local machine to make the developer experience faster. This allows you to not waste time re-building, re-testing, re-linting, or any number of other actions you might take on code that hasn't changed. Because the cache is stored locally, you are the only member of your team that can take advantage of these instant commands. You can manage and share this cache manually. @@ -107,4 +109,6 @@ workflows: You can also use our [ci-workflow generator](https://nx.dev/packages/workspace/generators/ci-workflow) to generate the configuration file. -Learn more about [configuring your CI](https://nx.app/docs/configuring-ci) environment using Nx Cloud with [Distributed Caching](https://nx.app/docs/distributed-caching) and [Distributed Task Execution](https://nx.app/docs/distributed-execution) in the Nx Cloud docs. +Learn more about configuring your CI environment using Nx Cloud with [Distributed Caching](/nx-cloud/set-up/set-up-caching) and [Distributed Task Execution](/nx-cloud/set-up/set-up-dte) in the Nx Cloud docs. + +
diff --git a/docs/shared/monorepo-ci-github-actions.md b/docs/shared/monorepo-ci-github-actions.md index b7fed515ba253..f599dfa8cbc97 100644 --- a/docs/shared/monorepo-ci-github-actions.md +++ b/docs/shared/monorepo-ci-github-actions.md @@ -14,7 +14,7 @@ But they come with their own technical challenges. The more code you add into yo ## Setting GitHub Actions -The `GitHub` can track the last successful run on `main` branch and use this as a reference point for the `BASE`. The `Nx Set SHAs` provides conventient implementation of this functionality which you can drop into you existing CI config. +The `GitHub` can track the last successful run on `main` branch and use this as a reference point for the `BASE`. The `Nx Set SHAs` provides convenient implementation of this functionality which you can drop into you existing CI config. To understand why knowing the last successful build is important for the affected command, check out the [in-depth explanation at Actions's docs](https://github.com/marketplace/actions/nx-set-shas#background). Below is an example of a GitHub setup for an Nx workspace only building and testing what is affected. For more details on how the orb is used, head over to the [official docs](https://github.com/marketplace/actions/nx-set-shas). @@ -46,6 +46,8 @@ jobs: The `pr` and `main` jobs implement the CI workflow. Setting `timeout-minutes` is needed only if you have very slow tasks. +
+ ## Distributed CI with Nx Cloud A computation cache is created on your local machine to make the developer experience faster. This allows you to not waste time re-building, re-testing, re-linting, or any number of other actions you might take on code that hasn't changed. Because the cache is stored locally, you are the only member of your team that can take advantage of these instant commands. You can manage and share this cache manually. @@ -84,4 +86,6 @@ jobs: You can also use our [ci-workflow generator](https://nx.dev/packages/workspace/generators/ci-workflow) to generate the workflow file. -Learn more about [configuring your CI](https://nx.app/docs/configuring-ci) environment using Nx Cloud with [Distributed Caching](https://nx.app/docs/distributed-caching) and [Distributed Task Execution](https://nx.app/docs/distributed-execution) in the Nx Cloud docs. +Learn more about configuring your CI environment using Nx Cloud with [Distributed Caching](/nx-cloud/set-up/set-up-caching) and [Distributed Task Execution](/nx-cloud/set-up/set-up-dte) in the Nx Cloud docs. + +
diff --git a/docs/shared/monorepo-ci-gitlab.md b/docs/shared/monorepo-ci-gitlab.md index c9910528192c6..d081668ad29fa 100644 --- a/docs/shared/monorepo-ci-gitlab.md +++ b/docs/shared/monorepo-ci-gitlab.md @@ -76,10 +76,14 @@ build: The `build` and `test` jobs implement the CI workflow using `.distributed` as template to keep CI configuration file more readable. +
+ ## Distributed CI with Nx Cloud A computation cache is created on your local machine to make the developer experience faster. This allows you to not waste time re-building, re-testing, re-linting, or any number of other actions you might take on code that hasn't changed. Because the cache is stored locally, you are the only member of your team that can take advantage of these instant commands. You can manage and share this cache manually. Nx Cloud allows this cache to be shared across your entire organization, meaning that any cacheable operation completed on your workspace only needs to be run once. Nx Cloud also allows you to distribute your CI across multiple machines to make sure the CI is fast even for very large repos. -Learn more about [configuring your CI](https://nx.app/docs/configuring-ci) environment using Nx Cloud with [Distributed Caching](https://nx.app/docs/distributed-caching) and [Distributed Task Execution](https://nx.app/docs/distributed-execution) in the Nx Cloud docs. +Learn more about configuring your CI environment using Nx Cloud with [Distributed Caching](/nx-cloud/set-up/set-up-caching) and [Distributed Task Execution](/nx-cloud/set-up/set-up-dte) in the Nx Cloud docs. + +
diff --git a/docs/shared/monorepo-ci-jenkins.md b/docs/shared/monorepo-ci-jenkins.md index e704f5b3d6d8b..35bf0833f9aac 100644 --- a/docs/shared/monorepo-ci-jenkins.md +++ b/docs/shared/monorepo-ci-jenkins.md @@ -65,6 +65,8 @@ pipeline { The `pr` and `main` jobs implement the CI workflow. +
+ ## Distributed CI with Nx Cloud A computation cache is created on your local machine to make the developer experience faster. This allows you to not waste time re-building, re-testing, re-linting, or any number of other actions you might take on code that hasn't changed. Because the cache is stored locally, you are the only member of your team that can take advantage of these instant commands. You can manage and share this cache manually. @@ -121,4 +123,6 @@ pipeline { } ``` -Learn more about [configuring your CI](https://nx.app/docs/configuring-ci) environment using Nx Cloud with [Distributed Caching](https://nx.app/docs/distributed-caching) and [Distributed Task Execution](https://nx.app/docs/distributed-execution) in the Nx Cloud docs. +Learn more about configuring your CI environment using Nx Cloud with [Distributed Caching](/nx-cloud/set-up/set-up-caching) and [Distributed Task Execution](/nx-cloud/set-up/set-up-dte) in the Nx Cloud docs. + +
diff --git a/docs/shared/nx-cloud-logo-horizontal-white.svg b/docs/shared/nx-cloud-logo-horizontal-white.svg new file mode 100644 index 0000000000000..9778d28f938c2 --- /dev/null +++ b/docs/shared/nx-cloud-logo-horizontal-white.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/docs/shared/using-nx/caching.md b/docs/shared/using-nx/caching.md index e63eeea745884..54afec7cbe426 100644 --- a/docs/shared/using-nx/caching.md +++ b/docs/shared/using-nx/caching.md @@ -199,6 +199,8 @@ The cache is stored in `node_modules/.cache/nx` by default. To change the cache By default, Nx uses a local computation cache. Nx stores the cached values only for a week, after which they are deleted. To clear the cache run `nx reset`, and Nx creates a new one the next time it tries to access it. +
+ ## Distributed Computation Caching The computation cache provided by Nx can be distributed across multiple machines. Nx Cloud is a product that allows you to share the results of running build/test with everyone else working in the same workspace. Learn more at [https://nx.app](https://nx.app). @@ -215,6 +217,34 @@ You can also distribute the cache manually using your own storage mechanisms. Be - By default, Nx also caches some computations necessary for calculating the project graph in the cache directory as well. - If you are using a shared volume where mutations to the cache are reflected immediately in other consumers, you should set `NX_PROJECT_GRAPH_CACHE_DIRECTORY` to a separate directory to separate it from the computation cache. +## Caching Priority + +Whenever you run a cacheable command with Nx, Nx attempts to fulfill that command using the first successful strategy in the following list: + +1. Check the local cache. If the command is cached there, replay the cached output. +2. Check the Nx Cloud distributed cache. If the command is cached there, store the cache locally and replay the cached output. +3. Run the command locally. Store the output in local cache. If you have a read-write access token, store the output in the Nx Cloud distributed cache. + +This algorithm optimizes for speed locally and minimizes unnecessary use of the distributed cache. + +## When is a Distributed Cache Helpful? + +Generally speaking, the bigger the organization, the more helpful a distributed cache becomes. However, distributed cache is still useful even in the following scenarios with two developers and a CI/CD machine. + +### Scenario 1: Help Me Fix This Bug + +Perry works on a feature, but he can't figure out why it isn't working the way he expects. Neelam checks out that branch to help. Neelam doesn't need to re-run all the tests that Perry already ran. + +### Scenario 2: Why Is This Breaking in CI? + +Tony pushes a branch up to CI, but CI doesn't pass. He asks Sofija to help. Sofija checks out that branch to troubleshoot. Sofija can reuse the output from CI instead of waiting for builds to run on her machine. + +### Scenario 3: CI Should Know It Already Did That + +Maya and Trey push up changes to two different apps that both depend on an unchanged shared buildable library. CI reuses the build output of the shared buildable library when building the apps in the two different PRs. + +
+ ## Example - [This is an example repo](https://github.com/vsavkin/large-monorepo) benchmarking Nx's computation caching. It also explains why Nx's computation caching tends to be a lot faster than the caching of other build systems. diff --git a/docs/shared/using-nx/dte.md b/docs/shared/using-nx/dte.md index 6aa9d232a0ad9..f9f13abc645d3 100644 --- a/docs/shared/using-nx/dte.md +++ b/docs/shared/using-nx/dte.md @@ -2,6 +2,8 @@ > Before reading this guide, check out the [mental model guide](/using-nx/mental-model). It will help you understand how computation caching fits into the rest of Nx. +
+ ## Overview Nx supports running commands across multiple machines. You can either set it up by hand ( @@ -32,3 +34,5 @@ it locally. These are the savings you get by enabling Distributed Task Execution in your CI config: ![DTE](/shared/using-nx/dte.png) + +
diff --git a/nx-dev/data-access-menu/src/lib/menu.api.ts b/nx-dev/data-access-menu/src/lib/menu.api.ts index 4e4edb45e3c1f..26423c5880258 100644 --- a/nx-dev/data-access-menu/src/lib/menu.api.ts +++ b/nx-dev/data-access-menu/src/lib/menu.api.ts @@ -1,5 +1,5 @@ import { DocumentMetadata } from '@nrwl/nx-dev/models-document'; -import { Menu, MenuSection } from '@nrwl/nx-dev/models-menu'; +import { Menu, MenuItem, MenuSection } from '@nrwl/nx-dev/models-menu'; import { createMenuItems, getBasicSection, @@ -12,7 +12,8 @@ export class MenuApi { constructor( private readonly documents: DocumentMetadata, - private readonly packageDocuments: DocumentMetadata[] = [] + private readonly packageDocuments: DocumentMetadata[] = [], + private readonly extractorFunctions: ((x: MenuItem[]) => MenuSection)[] = [] ) {} getMenu(): Menu { @@ -21,17 +22,23 @@ export class MenuApi { if (menu) return menu; const items = createMenuItems(this.documents); - if (items) { - menu = { - sections: [getBasicSection(items), getDeepDiveSection(items)], - }; - if (!!this.packageDocuments.length) - menu.sections.push( - this.getReferenceApiMenuSection(this.packageDocuments) - ); - } else { - throw new Error(`Cannot find any documents`); - } + if (!items) throw new Error(`Cannot find any documents`); + + menu = { + sections: this.extractorFunctions.map((categorizer) => + categorizer( + items.length === 1 && items[0].id === 'nx-cloud' + ? (items[0].itemList as MenuItem[]) + : items + ) + ), + }; + + if (!!this.packageDocuments.length) + menu.sections.push( + this.getReferenceApiMenuSection(this.packageDocuments) + ); + this.menuCache = menu; return menu; diff --git a/nx-dev/data-access-menu/src/lib/menu.utils.ts b/nx-dev/data-access-menu/src/lib/menu.utils.ts index c2255fb87c0d4..ac04c9b02b5c1 100644 --- a/nx-dev/data-access-menu/src/lib/menu.utils.ts +++ b/nx-dev/data-access-menu/src/lib/menu.utils.ts @@ -101,3 +101,38 @@ export function getPackageApiSection(items: MenuItem[]): MenuSection { ), }; } + +export function getBasicNxCloudSection(items: MenuItem[]): MenuSection { + return { + id: 'basic', + name: 'Basic', + hideSectionHeader: true, + itemList: items + .filter( + (m) => m.id === 'intro' || m.id === 'set-up' || m.id === 'account' + ) + .map((m) => { + return { + ...m, + disableCollapsible: !m.id.endsWith('tutorial'), + }; + }), + }; +} + +export function getDeepDiveNxCloudSection(items: MenuItem[]): MenuSection { + return { + id: 'deep-dive', + name: 'Deep Dive', + itemList: items + .filter((m) => m.id === 'private-cloud' || m.id === 'reference') + .map((m) => ({ + ...m, + disableCollapsible: true, + itemList: m.itemList?.map((item) => ({ + ...item, + disableCollapsible: true, + })), + })), + }; +} diff --git a/nx-dev/feature-doc-viewer/src/lib/content.tsx b/nx-dev/feature-doc-viewer/src/lib/content.tsx index 288f8f32cc836..88567e8362175 100644 --- a/nx-dev/feature-doc-viewer/src/lib/content.tsx +++ b/nx-dev/feature-doc-viewer/src/lib/content.tsx @@ -2,6 +2,7 @@ import { sendCustomEvent } from '@nrwl/nx-dev/feature-analytics'; import { DocumentData } from '@nrwl/nx-dev/models-document'; import { ReactComponentElement } from 'react'; import ReactMarkdown from 'react-markdown'; +import raw from 'rehype-raw'; import autolinkHeadings from 'rehype-autolink-headings'; import slug from 'rehype-slug'; import gfm from 'remark-gfm'; @@ -48,6 +49,7 @@ export function Content(props: ContentProps): ReactComponentElement { remarkPlugins={[gfm]} rehypePlugins={[ slug, + raw, [ autolinkHeadings, { diff --git a/nx-dev/nx-dev-e2e/src/integration/nx-cloud-documentation.spec.ts b/nx-dev/nx-dev-e2e/src/integration/nx-cloud-documentation.spec.ts new file mode 100644 index 0000000000000..97ea4a101e359 --- /dev/null +++ b/nx-dev/nx-dev-e2e/src/integration/nx-cloud-documentation.spec.ts @@ -0,0 +1,103 @@ +import { assertTextOnPage } from './helpers'; + +/** + * Asserting all the additional API references pages are accounted for and accessible. + * Generation of the pages is manual since we want to make sure the change is intended. + */ +describe('nx-dev: Nx Cloud section', () => { + (<{ title: string; path: string }[]>[ + { title: 'What is Nx Cloud?', path: '/nx-cloud/intro/what-is-nx-cloud' }, + { + title: 'Adding Nx Cloud to an Nx Workspace', + path: '/nx-cloud/set-up/set-up-caching', + }, + { + title: 'Set Up Distributed Task Execution', + path: '/nx-cloud/set-up/set-up-dte', + }, + { + title: 'Recording Non-Nx Commands', + path: '/nx-cloud/set-up/record-commands', + }, + { + title: 'Enable Github PR Integration', + path: '/nx-cloud/set-up/github', + }, + { + title: 'Billing and Utilization', + path: '/nx-cloud/account/billing', + }, + { + title: 'User Management', + path: '/nx-cloud/account/users', + }, + { + title: 'Connecting Nx Cloud to your existing Google identity provider', + path: '/nx-cloud/account/google-auth', + }, + { + title: 'Access Tokens', + path: '/nx-cloud/account/access-tokens', + }, + { + title: 'Security Scenarios', + path: '/nx-cloud/account/scenarios', + }, + { + title: 'End to End Encryption', + path: '/nx-cloud/account/encryption', + }, + { + title: 'Getting Started with Nx Private Cloud', + path: '/nx-cloud/private-cloud/get-started', + }, + { + title: 'Private Cloud GitHub PR Integration', + path: '/nx-cloud/private-cloud/github', + }, + { + title: 'Nx Private Cloud and Kubernetes', + path: '/nx-cloud/private-cloud/deploy-kubernetes', + }, + { + title: 'Deploying Nx Private Cloud to AWS', + path: '/nx-cloud/private-cloud/deploy-aws', + }, + { + title: 'Deploying Nx Private Cloud to Azure', + path: '/nx-cloud/private-cloud/deploy-azure', + }, + { + title: 'Nx Private Cloud Auth', + path: '/nx-cloud/private-cloud/auth-single-admin', + }, + { + title: 'Nx Private Cloud GitHub Auth', + path: '/nx-cloud/private-cloud/auth-github', + }, + { + title: 'Nx Private Cloud GitLab Auth', + path: '/nx-cloud/private-cloud/auth-gitlab', + }, + { + title: 'Advanced Configuration', + path: '/nx-cloud/private-cloud/advanced-config', + }, + { + title: 'Configuring the Cloud Runner / Nx CLI', + path: '/nx-cloud/reference/config', + }, + { + title: 'Environment Variables', + path: '/nx-cloud/reference/env-vars', + }, + { + title: 'Nx Cloud Server API Reference', + path: '/nx-cloud/reference/server-api', + }, + { + title: '@nrwl/nx-cloudNx Private Cloud', + path: '/nx-cloud/reference/release-notes', + }, + ]).forEach((page) => assertTextOnPage(page.path, page.title)); +}); diff --git a/nx-dev/nx-dev/lib/api.ts b/nx-dev/nx-dev/lib/api.ts index 247101a657e66..f08d06be5b0a0 100644 --- a/nx-dev/nx-dev/lib/api.ts +++ b/nx-dev/nx-dev/lib/api.ts @@ -2,6 +2,12 @@ import { DocumentsApi } from '@nrwl/nx-dev/data-access-documents/node-only'; import { MenuApi } from '@nrwl/nx-dev/data-access-menu'; import { PackagesApi } from '@nrwl/nx-dev/data-access-packages/node-only'; import { DocumentMetadata } from '@nrwl/nx-dev/models-document'; +import { + getBasicNxCloudSection, + getBasicSection, + getDeepDiveNxCloudSection, + getDeepDiveSection, +} from '../../data-access-menu/src/lib/menu.utils'; // Imports JSON directly, so they can be bundled into the app and functions. // Also provides some test safety. @@ -22,7 +28,22 @@ export const nxDocumentsApi = new DocumentsApi({ addAncestor: null, }); +export const nxCloudDocumentsApi = new DocumentsApi({ + publicDocsRoot: 'nx-dev/nx-dev/public/documentation', + documentSources: [ + documents.find((x) => x.id === 'nx-cloud-documentation'), + ].filter((x) => !!x) as DocumentMetadata[], + addAncestor: { id: 'nx-cloud', name: 'Nx Cloud' }, +}); + export const nxMenuApi = new MenuApi( nxDocumentsApi.getDocuments(), - packagesApi.getPackageDocuments().itemList as DocumentMetadata[] + packagesApi.getPackageDocuments().itemList as DocumentMetadata[], + [getBasicSection, getDeepDiveSection] +); + +export const nxCloudMenuApi = new MenuApi( + nxCloudDocumentsApi.getDocuments(), + [], + [getBasicNxCloudSection, getDeepDiveNxCloudSection] ); diff --git a/nx-dev/nx-dev/pages/[...segments].tsx b/nx-dev/nx-dev/pages/[...segments].tsx index 14f7c7756f120..36eb2b82700ca 100644 --- a/nx-dev/nx-dev/pages/[...segments].tsx +++ b/nx-dev/nx-dev/pages/[...segments].tsx @@ -10,7 +10,13 @@ import { Footer, Header } from '@nrwl/nx-dev/ui-common'; import cx from 'classnames'; import Router from 'next/router'; import { useCallback, useEffect, useState } from 'react'; -import { nxDocumentsApi, nxMenuApi, packagesApi } from '../lib/api'; +import { + nxCloudDocumentsApi, + nxCloudMenuApi, + nxDocumentsApi, + nxMenuApi, + packagesApi, +} from '../lib/api'; interface DocumentationPageProps { menu: Menu; @@ -143,7 +149,15 @@ export async function getStaticProps({ }: { params: { segments: string[] }; }) { - const menu = nxMenuApi.getMenu(); + // Set Document and Menu apis + let documentsApi = nxDocumentsApi; + let menuApi = nxMenuApi; + if (params.segments[0] === 'nx-cloud') { + documentsApi = nxCloudDocumentsApi; + menuApi = nxCloudMenuApi; + } + + const menu = menuApi.getMenu(); if (params.segments[0] === 'packages') { let pkg: PackageMetadata | null = null; @@ -192,7 +206,7 @@ export async function getStaticProps({ let document: DocumentData | undefined; try { - document = nxDocumentsApi.getDocument(params.segments); + document = documentsApi.getDocument(params.segments); } catch (e) { // Do nothing } @@ -221,6 +235,7 @@ export async function getStaticPaths() { paths: [ ...packagesApi.getStaticPackagePaths(), ...nxDocumentsApi.getStaticDocumentPaths(), + ...nxCloudDocumentsApi.getStaticDocumentPaths(), ], fallback: 'blocking', }; diff --git a/nx-dev/nx-dev/styles/main.css b/nx-dev/nx-dev/styles/main.css index 7dfb73a270c45..6c16ebe665442 100644 --- a/nx-dev/nx-dev/styles/main.css +++ b/nx-dev/nx-dev/styles/main.css @@ -55,6 +55,17 @@ iframe[src*='youtube'] { width: max-content; } +.prose iframe[src^="https://nx.app"] +{ + border: 1px solid hsla(0, 0%, 85%, 1); + border-radius: 0.375rem; + box-shadow: 0 2px 6px hsla(0, 0%, 95%, 1); + height: 80vh; + max-width: 100%; + overflow: hidden; + width: 100%; +} + /* Code embed */ @@ -173,3 +184,18 @@ iframe[src*='youtube'] { opacity: 1; visibility: visible; } + +/* Nx Cloud section */ +.nx-cloud-section { + border-left-width: 0.25em; + border-left-color: hsla(162, 47%, 50%, 1); + padding-left: 1em; + margin-left: -1.25em; +} + +.nx-cloud-section h2 { + background: url('/documentation/shared/nx-cloud-logo-horizontal-white.svg') + no-repeat left center; + background-size: contain; + padding-left: 40px; +} diff --git a/nx-dev/ui-common/src/lib/header.tsx b/nx-dev/ui-common/src/lib/header.tsx index 42410548dd252..ee4cdc8149bb8 100644 --- a/nx-dev/ui-common/src/lib/header.tsx +++ b/nx-dev/ui-common/src/lib/header.tsx @@ -69,7 +69,18 @@ export function Header(props: HeaderProps) { !!props.isDocViewer ? 'font-bold' : '' )} > - Docs + Nx Docs + + + + + Nx Cloud Docs diff --git a/nx-dev/ui-common/src/lib/sidebar.tsx b/nx-dev/ui-common/src/lib/sidebar.tsx index 5819fa099315a..5e7e116754ad5 100644 --- a/nx-dev/ui-common/src/lib/sidebar.tsx +++ b/nx-dev/ui-common/src/lib/sidebar.tsx @@ -107,6 +107,9 @@ function SidebarSectionItems({