ci: upgrade Nx and migrate worker configuration

.github/workflows/pr.yml

@@ -10,6 +10,13 @@ concurrency:
 env:
   NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
   SERVER_PRESET: 'node-server'
+  # Enable dynamic task packing for distributed CI.
+  NX_CLOUD_AGENT_TASK_QUEUE: true
+  NX_CLOUD_AUTO_TASK_PACKING: true
+  NX_CLOUD_AGENT_UNCAPPED_GROUP_WORK: true
+  NX_CLOUD_PACKING_MEM_MULTIPLIER: 1.5
+  NX_CLOUD_BUFFER_TASK_COMPLETIONS: true
+  NX_CLOUD_CONTINUOUS_ASSIGNMENT: true
 
 permissions:
   contents: read
@@ -26,8 +33,8 @@ jobs:
         with:
           fetch-depth: 0
           persist-credentials: false
-      - name: Start Nx Agents
-        run: npx nx-cloud start-ci-run --distribute-on=".nx/workflows/dynamic-changesets.yaml"
+      - name: Start Nx Workers
+        run: npx nx-cloud start-workers
       - name: Setup Tools
         uses: TanStack/config/.github/setup@e4b48f16568324f76f467aa4c2aac2f05db632c3 # main
       - name: Get base and head commits for `nx affected`
@@ -36,9 +43,9 @@ jobs:
           main-branch-name: main
       - name: Run Checks
         run: pnpm run test:pr --parallel=3
-      - name: Stop Nx Agents
+      - name: Stop Nx Workers
         if: ${{ always() }}
-        run: npx nx-cloud stop-all-agents
+        run: npx nx-cloud stop-all-workers
   preview:
     name: Preview
     runs-on: ubuntu-latest

.nx/ci-config.yaml

@@ -0,0 +1,5 @@
+dte:
+  distribute-on:
+    small-changeset: 6 linux-medium-js
+    medium-changeset: 12 linux-medium-js
+    large-changeset: 18 linux-medium-js

.nx/workflows/sandboxing-config.yaml → .nx/workflows/ultracache-config.yaml

@@ -1,21 +1,21 @@
-exclude-reads:
+ignore-reads:
   - e2e/.gitignore
   - '**/src/routeTree.gen.ts'
-exclude-writes:
+ignore-writes:
   - '**/src/routeTree.gen.ts'
 task-exclusions:
   - target: test:build
-    exclude-reads:
+    ignore-reads:
       - LICENSE
   # HMR tests edit these inputs in place and restore their original contents.
   # Keep them out of cached outputs so cache replay never overwrites source.
   - project: tanstack-react-start-e2e-deferred-hydration
     target: test:e2e
-    exclude-writes:
+    ignore-writes:
       - e2e/react-start/deferred-hydration/src/routes/components.tsx
   - project: tanstack-react-start-e2e-hmr
     target: test:e2e
-    exclude-writes: &hmr-source-writes
+    ignore-writes: &hmr-source-writes
       - e2e/react-start/hmr/src/components/AliasedRouteImportChildPanel.tsx
       - e2e/react-start/hmr/src/components/AliasedRouteImportParentPanel.tsx
       - e2e/react-start/hmr/src/hmr/server-fn-hmr-factory.ts
@@ -32,93 +32,93 @@ task-exclusions:
       - e2e/react-start/hmr/src/routes/inputs.tsx
   - project: tanstack-react-start-e2e-hmr
     target: test:e2e--vite-ssr
-    exclude-writes: *hmr-source-writes
+    ignore-writes: *hmr-source-writes
   - project: tanstack-react-start-e2e-hmr
     target: test:e2e--vite-ssr--bundled-dev
-    exclude-writes: *hmr-source-writes
+    ignore-writes: *hmr-source-writes
   - project: tanstack-react-start-e2e-hmr
     target: test:e2e--rsbuild-ssr
-    exclude-writes: *hmr-source-writes
+    ignore-writes: *hmr-source-writes
   - project: tanstack-react-start-e2e-rsbuild
     target: test:e2e--rsbuild-ssr
-    exclude-writes:
+    ignore-writes:
       - e2e/react-start/rsbuild/src/routes/index.tsx
   - project: tanstack-react-start-e2e-server-functions
     target: test:e2e
-    exclude-writes:
+    ignore-writes:
       - e2e/react-start/server-functions/src/routes/consistent.tsx
   # Scaffolding tests deliberately populate tracked empty route fixtures.
   - project: '@tanstack/router-generator'
     target: test:unit
-    exclude-writes:
+    ignore-writes:
       - packages/router-generator/tests/generator/custom-scaffolding/routes/__root.tsx
       - packages/router-generator/tests/generator/custom-scaffolding/routes/api/bar.tsx
       - packages/router-generator/tests/generator/custom-scaffolding/routes/foo.lazy.tsx
       - packages/router-generator/tests/generator/custom-scaffolding/routes/index.tsx
   # These reads are of scratch files created by the same test invocation.
   - project: tanstack-solid-start-e2e-basic-auth
     target: test:e2e
-    exclude-reads:
+    ignore-reads:
       - e2e/solid-start/basic-auth/.tmp/dev.db
   - project: tanstack-vue-start-e2e-basic-auth
     target: test:e2e
-    exclude-reads:
+    ignore-reads:
       - e2e/vue-start/basic-auth/.tmp/dev.db
   - project: '@tanstack/router-generator'
     target: test:unit
-    exclude-reads:
+    ignore-reads:
       - packages/router-generator/tests/generator/file-modification/routes/[(]test[)]/initiallyEmpty.tsx
       - packages/router-generator/tests/generator/file-modification/routes/[(]test[)]/initiallyEmpty.lazy.tsx
   # Mutable counters are scratch state, not artifacts to replay from cache.
   - project: tanstack-react-start-e2e-basic-tsr-config
     target: test:e2e
-    exclude-reads:
+    ignore-reads:
       - e2e/react-start/basic-tsr-config/count.txt
-    exclude-writes:
+    ignore-writes:
       - e2e/react-start/basic-tsr-config/count.txt
   - project: tanstack-solid-start-e2e-basic-tsr-config
     target: test:e2e
-    exclude-reads:
+    ignore-reads:
       - e2e/solid-start/basic-tsr-config/count.txt
-    exclude-writes:
+    ignore-writes:
       - e2e/solid-start/basic-tsr-config/count.txt
   - project: tanstack-vue-start-e2e-basic-tsr-config
     target: test:e2e
-    exclude-reads:
+    ignore-reads:
       - e2e/vue-start/basic-tsr-config/count.txt
-    exclude-writes:
+    ignore-writes:
       - e2e/vue-start/basic-tsr-config/count.txt
   # Paraglide downloads compiler plugins from the URLs in settings.json.
   # Ignore warm-cache reads; the settings remain inputs and cache files outputs.
   - project: tanstack-react-start-e2e-i18n-paraglide
     target: build
-    exclude-reads:
+    ignore-reads:
       - e2e/react-start/i18n-paraglide/project.inlang/cache/plugins/*
   - project: tanstack-router-e2e-react-i18n-paraglide
     target: build
-    exclude-reads:
+    ignore-reads:
       - e2e/react-router/i18n-paraglide/project.inlang/cache/plugins/*
   - project: tanstack-react-start-e2e-i18n-paraglide
     target: test:e2e
-    exclude-reads:
+    ignore-reads:
       - e2e/react-start/i18n-paraglide/project.inlang/cache/plugins/*
   - project: tanstack-router-e2e-react-i18n-paraglide
     target: test:e2e
-    exclude-reads:
+    ignore-reads:
       - e2e/react-router/i18n-paraglide/project.inlang/cache/plugins/*
   - project: tanstack-router-i18n-paraglide
     target: build
-    exclude-reads:
+    ignore-reads:
       - examples/react/i18n-paraglide/project.inlang/cache/plugins/*
   - project: tanstack-start-i18n-paraglide
     target: build
-    exclude-reads:
+    ignore-reads:
       - examples/react/start-i18n-paraglide/project.inlang/cache/plugins/*
   - project: tanstack-router-solid-i18n-paraglide
     target: build
-    exclude-reads:
+    ignore-reads:
       - examples/solid/i18n-paraglide/project.inlang/cache/plugins/*
   - project: tanstack-solid-start-i18n-paraglide
     target: build
-    exclude-reads:
+    ignore-reads:
       - examples/solid/start-i18n-paraglide/project.inlang/cache/plugins/*

AGENTS.md

@@ -15,10 +15,12 @@
 - For sandbox-blocked registry/store access, escalate the same command; report the blocker if unavailable. Do not change stores, delete dependencies/lockfiles, use `--force`/`--ignore-scripts`, or weaken workspace trust/build policies to bypass it.
 - Never manually edit `pnpm-lock.yaml` or any `routeTree.gen.ts`. Regenerate the lockfile with `pnpm install --no-frozen-lockfile` after intentional dependency changes; regenerate route trees through app builds/dev servers or the generator fixture harness.
 - Always use control-flow braces. Run `pnpm format` before validation.
-- Use Nx: workspace imports consume built packages, so direct runners can test stale dependencies. Inspect resolved targets; some are inferred.
+- Use Nx: workspace imports consume built packages, so direct runners can test stale dependencies. Inspect resolved targets with `pnpm nx show project <project> --json`; some are inferred.
+- Run finite validation through `run-many` with explicit projects and targets, including a single project/target. Nx automatically selects `summary` output when it detects an AI agent: omit `--outputStyle` for normal runs. Read the reported full log files for failures; use `--outputStyle=summary` if agent detection is unavailable.
+- Use `--outputStyle=static` or `pnpm nx run <project>:<target>` only when diagnosing a task and its full output is needed. Continuous/watch targets may use live output.
 
 ```sh
-CI=1 NX_DAEMON=false pnpm nx run <project>:<target> --outputStyle=stream --skipRemoteCache
+CI=1 NX_DAEMON=false pnpm nx run-many -p <project> -t <target> --skipRemoteCache
 ```
 
 - Run one Nx command at a time. For a ~20-second startup/graph stall, stop, run `pnpm nx reset`, and retry once, then escalate. Do not apply that timeout to running tests.

nx.json

@@ -1,6 +1,7 @@
 {
   "$schema": "./node_modules/nx/schemas/nx-schema.json",
   "defaultBase": "main",
+  "bust": "nx24-exclusive-e2e-16-medium-baseline-2026-10-25-05",
   "nxCloudId": "6442f7de8226a6291646a813",
   "useInferencePlugins": false,
   "parallel": 5,
@@ -10,7 +11,10 @@
   "namedInputs": {
     "sharedGlobals": [
       "{workspaceRoot}/.npmrc",
-      "{workspaceRoot}/.nx/workflows/sandboxing-config.yaml",
+      "{workspaceRoot}/nx.json",
+      "{workspaceRoot}/.github/workflows/pr.yml",
+      "{workspaceRoot}/.nx/ci-config.yaml",
+      "{workspaceRoot}/.nx/workflows/ultracache-config.yaml",
       "{workspaceRoot}/.nvmrc",
       "{workspaceRoot}/package.json",
       "{workspaceRoot}/tsconfig.json"
@@ -41,7 +45,7 @@
   "targetDefaults": {
     "test:docs": {
       "cache": true,
-      "inputs": ["{workspaceRoot}/docs/**/*"]
+      "inputs": ["sharedGlobals", "{workspaceRoot}/docs/**/*"]
     },
     "test:eslint": {
       "cache": true,

package.json

@@ -65,15 +65,15 @@
   "devDependencies": {
     "@changesets/changelog-github": "^0.7.0",
     "@changesets/cli": "^2.30.0",
-    "@nx/devkit": "23.2.0",
+    "@nx/devkit": "24.0.0",
     "@playwright/test": "catalog:",
     "@swc-node/register": "^1.11.1",
     "@tanstack/eslint-config": "0.4.0",
     "@types/node": "catalog:",
     "eslint": "catalog:",
     "eslint-plugin-unused-imports": "^4.1.4",
     "markdown-link-extractor": "^4.0.3",
-    "nx": "23.2.0",
+    "nx": "24.0.0",
     "prettier": "^3.8.0",
     "tinyglobby": "^0.2.15",
     "typescript": "npm:@typescript/typescript6@^6.0.2",

packages/router-core/AGENTS.md

@@ -8,5 +8,5 @@
 - Backpressure tests are excluded from normal unit runs. For buffering/backpressure changes, run the gated suite below. Its memory case requires exposed GC; bypass Nx cache so a previous run with the gate disabled cannot count as validation.
 
 ```sh
-RUN_BACKPRESSURE_PERF=1 CI=1 NX_DAEMON=false pnpm nx run @tanstack/router-core:test:unit --outputStyle=stream --skipRemoteCache --skipNxCache -- tests/transformStreamBackpressure.perf.test.ts --pool=forks --execArgv=--expose-gc
+RUN_BACKPRESSURE_PERF=1 CI=1 NX_DAEMON=false pnpm nx run-many -p @tanstack/router-core -t test:unit --skipRemoteCache --skipNxCache -- tests/transformStreamBackpressure.perf.test.ts --pool=forks --execArgv=--expose-gc
 ```

packages/router-ssr-query-core/AGENTS.md

@@ -5,5 +5,5 @@ Register QueryClient teardown at SSR attachment, before loading/dehydration can
 For query retention or cleanup changes, enable the GC tests that normal unit runs skip. `RUN_SSR_GC_TESTS=1` configures forked workers with exposed GC. Bypass Nx cache so a previous run with the gate disabled cannot count as validation.
 
 ```sh
-RUN_SSR_GC_TESTS=1 CI=1 NX_DAEMON=false pnpm nx run @tanstack/router-ssr-query-core:test:unit --outputStyle=stream --skipRemoteCache --skipNxCache -- tests/index.test.ts
+RUN_SSR_GC_TESTS=1 CI=1 NX_DAEMON=false pnpm nx run-many -p @tanstack/router-ssr-query-core -t test:unit --skipRemoteCache --skipNxCache -- tests/index.test.ts
 ```