docs(nx-cloud): caching workspace data

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",

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",

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"
                 }
               ]
             }

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
+```

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.

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)