diff --git a/docs/generated/manifests/ci.json b/docs/generated/manifests/ci.json index 87360ecb883a9..4f778c0488252 100644 --- a/docs/generated/manifests/ci.json +++ b/docs/generated/manifests/ci.json @@ -926,6 +926,17 @@ "isExternal": false, "path": "/ci/recipes/other/cipe-affected-project-graph", "tags": [] + }, + { + "id": "cache-nx-generated-metadata", + "name": "Cache Nx generated metadata", + "description": "", + "mediaImage": "", + "file": "nx-cloud/recipes/cache-nx-generated-metadata", + "itemList": [], + "isExternal": false, + "path": "/ci/recipes/other/cache-nx-generated-metadata", + "tags": [] } ], "isExternal": false, @@ -1899,6 +1910,17 @@ "isExternal": false, "path": "/ci/recipes/other/cipe-affected-project-graph", "tags": [] + }, + { + "id": "cache-nx-generated-metadata", + "name": "Cache Nx generated metadata", + "description": "", + "mediaImage": "", + "file": "nx-cloud/recipes/cache-nx-generated-metadata", + "itemList": [], + "isExternal": false, + "path": "/ci/recipes/other/cache-nx-generated-metadata", + "tags": [] } ], "isExternal": false, @@ -1938,6 +1960,17 @@ "path": "/ci/recipes/other/cipe-affected-project-graph", "tags": [] }, + "/ci/recipes/other/cache-nx-generated-metadata": { + "id": "cache-nx-generated-metadata", + "name": "Cache Nx generated metadata", + "description": "", + "mediaImage": "", + "file": "nx-cloud/recipes/cache-nx-generated-metadata", + "itemList": [], + "isExternal": false, + "path": "/ci/recipes/other/cache-nx-generated-metadata", + "tags": [] + }, "/ci/reference": { "id": "reference", "name": "Reference", diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index ca0e84e1ebfea..019b060efc643 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -6139,6 +6139,14 @@ "isExternal": false, "children": [], "disableCollapsible": false + }, + { + "name": "Cache Nx generated metadata", + "path": "/ci/recipes/other/cache-nx-generated-metadata", + "id": "cache-nx-generated-metadata", + "isExternal": false, + "children": [], + "disableCollapsible": false } ], "disableCollapsible": false @@ -6849,6 +6857,14 @@ "isExternal": false, "children": [], "disableCollapsible": false + }, + { + "name": "Cache Nx generated metadata", + "path": "/ci/recipes/other/cache-nx-generated-metadata", + "id": "cache-nx-generated-metadata", + "isExternal": false, + "children": [], + "disableCollapsible": false } ], "disableCollapsible": false @@ -6877,6 +6893,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Cache Nx generated metadata", + "path": "/ci/recipes/other/cache-nx-generated-metadata", + "id": "cache-nx-generated-metadata", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Reference", "path": "/ci/reference", diff --git a/docs/map.json b/docs/map.json index 9e384f7fbbdc9..81ab9a4f4429f 100644 --- a/docs/map.json +++ b/docs/map.json @@ -2007,6 +2007,11 @@ "name": "Reduce the Number of Affected Projects in a CI Pipeline Execution", "id": "cipe-affected-project-graph", "file": "nx-cloud/recipes/cipe-affected-project-graph" + }, + { + "name": "Cache Nx generated metadata", + "id": "cache-nx-generated-metadata", + "file": "nx-cloud/recipes/cache-nx-generated-metadata" } ] } diff --git a/docs/nx-cloud/recipes/cache-nx-generated-metadata.md b/docs/nx-cloud/recipes/cache-nx-generated-metadata.md new file mode 100644 index 0000000000000..d58380fdf2bf1 --- /dev/null +++ b/docs/nx-cloud/recipes/cache-nx-generated-metadata.md @@ -0,0 +1,46 @@ +# Speed up your CI by caching Nx generated metadata + +Nx generates metadata files—referred to as workspace data—on initialization, which it uses to intelligently run commands and integrate with plugins. Large monorepos often contain numerous projects with complex relationships, making metadata generation more time-consuming. + +Updating existing workspace data is faster than creating it from scratch. To avoid regenerating this data for each CI run, Nx Cloud supports workspace data caching. By caching workspace data from previous runs and reusing it in future runs, we can reduce the time needed to prepare the workspace. + +## How does it work? + +When in a CI context, Nx Cloud will automatically cache the contents of your workspace data and upload it to our remote cache. +This data will only be uploaded when you run CI on your workspaces default branch. + +To leverage your cached workspace data, you can use the following command while authenticated with `read-write` access: + +```bash +npx nx-cloud get-workspace-data +``` + +This will download your cached workspace data to your workspace. + +## What does this look like in practice? + +The following is an example of a CI configuration that uses the `get-workspace-data` command to download the workspace data: + +```yaml +name: Nx Cloud - CI +on: + push: + branches: + - main + pull_request: + branches: + - main +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: + node-version: 18 + - run: npx nx-cloud@latest start-ci-run + + # Invoke this command before your first nx command + - run: npx nx-cloud get-workspace-data + - run: npx nx affected +``` diff --git a/docs/nx-cloud/reference/nx-cloud-cli.md b/docs/nx-cloud/reference/nx-cloud-cli.md index fee8056dfb12e..353ac5c891569 100644 --- a/docs/nx-cloud/reference/nx-cloud-cli.md +++ b/docs/nx-cloud/reference/nx-cloud-cli.md @@ -235,3 +235,7 @@ Same as `npx nx-cloud complete-ci-run`. This command tells Nx Cloud to terminate all agents associated with this CI pipeline execution. Invoking this command is not needed anymore. New versions of Nx Cloud can track when the main job terminates and terminate associated agents automatically. + +## npx nx-cloud get-workspace-data + +Retrieves [cached Nx generated metadata](/ci/recipes/other/cache-nx-generated-metadata) for your workspace. If no cached workspace data exists for the workspace, Nx will generate your workspaces metadata as normal. diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index b8c078c46f069..c0e2545f7ea94 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -323,6 +323,7 @@ - [Record Non-Nx Commands](/ci/recipes/other/record-commands) - [Prepare applications for deployment via CI](/ci/recipes/other/ci-deployment) - [Reduce the Number of Affected Projects in a CI Pipeline Execution](/ci/recipes/other/cipe-affected-project-graph) + - [Cache Nx generated metadata](/ci/recipes/other/cache-nx-generated-metadata) - [Reference](/ci/reference) - [Configuration Options](/ci/reference/config) - [nx-cloud CLI](/ci/reference/nx-cloud-cli)