Skip to content

feat: add Nx shadow build system alongside fluid-build#26718

Draft
tylerbutler wants to merge 21 commits intomicrosoft:mainfrom
tylerbutler:nx-shadow-build-pilot
Draft

feat: add Nx shadow build system alongside fluid-build#26718
tylerbutler wants to merge 21 commits intomicrosoft:mainfrom
tylerbutler:nx-shadow-build-pilot

Conversation

@tylerbutler
Copy link
Copy Markdown
Member

@tylerbutler tylerbutler commented Mar 13, 2026

Background

We have long talked about moving off of fluid-build onto a more standard build system. Thanks to many changes to fluid-build over the years, it's easier now to set up a shadow build using Nx, so I did. This enables using Nx locally for cross-build caching, while still using fluid-build as the main build system. If Nx goes well, then we can pursue it. If it goes poorly, then we can remove it without much hassle.

Observations

  • Nx is slower than fluid-build.
  • Nx seems to run a lot more tasks when fully cached than fluid-build.
  • The task dependencies are not quite right. They're good enough to get going, but they'll need tweaking to be fully correct.

Summary of changes

  • Adds Nx as a shadow build orchestrator running alongside the existing fluid-build system across the client and build-tools release groups
  • Introduces nx.json configuration at both the repo root (client) and build-tools/ with task dependency graphs, named inputs, cache settings, and target defaults that mirror the existing fluid-build task graph
  • Adds 149 project.json files across all packages to override orchestrator tasks (e.g. build, compile, lint) with nx:noop, preventing Nx from invoking fluid-build scripts while letting executor tasks (e.g. tsc, eslint, test:mocha) run their real commands
  • Includes per-package dependency overrides for packages with custom fluidBuild.tasks (e.g. client-utils, presence, tree, sequence, test-end-to-end-tests) to ensure Nx task prerequisites match fluid-build behavior
  • Adds nx:* convenience scripts to root package.json files for running Nx commands (nx:build, nx:tsc, nx:affected:build, nx:graph, etc.)
  • Adds nx and @nx/js/@nx/workspace as dev dependencies; updates pnpm lockfiles
  • Documents the migration approach in docs/nx-migration-plan.md and build-tools/plans/nx-shadow-build-guide.md
  • Adds .nx/ to .gitignore and .nxignore for cache and build-tools exclusions

tylerbutler and others added 8 commits March 11, 2026 23:49
Add project.json files to all build-tools packages to override
orchestrator tasks (build, build:compile, compile, lint,
build:commonjs) with nx:noop executor. This prevents NX from
invoking fluid-build when running shadow builds.

Add plans/nx-shadow-build-guide.md documenting the step-by-step
process for standing up a shadow NX build in any release group,
including task classification, cache input/output configuration,
and lessons learned from the build-tools pilot.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Client-utils uses custom build:exports:browser/node scripts instead of
api-extractor:esnext/commonjs, breaking several nx dependency chains.
Added per-target dependsOn overrides for build:exports, build:test,
check:exports, build:api-reports, and ci:build:api-reports targets.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…tions

Mirror fluidBuild.tasks overrides from package.json into NX project.json
files to ensure the NX shadow build has correct dependency chains.

Fixes applied across 17 packages in several categories:
- Cross-package deps (sequence, test-dds-utils, tree, local-server-stress-tests)
- Custom build pipeline (presence: tsc:main/experimental, build:esnext:main/experimental)
- Test-only packages (azure-client, odsp-client, local-server-tests, test-end-to-end-tests)
- Broken check:exports chains (devtools-view, example-utils, test-version-utils, test-loader-utils, test-pairwise-generator)
- Webpack chains (bundle-size-tests, webpack-fluid-loader)
- Non-standard targets (core-interfaces: build:test:esm:no-exactOptionalPropertyTypes)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
build-tools, server/routerlicious, server/gitrest, and server/historian
are separate pnpm workspaces with their own nx.json. Without .nxignore,
the root `nx run-many` discovers their packages and tries to build them.
@tylerbutler tylerbutler self-assigned this Mar 13, 2026
Add missing rollup .d.ts outputs to api-extractor cache config so
generated entrypoint files survive cache restore. Add upstream build
deps (^tsc, ^build:esnext, ^api) to eslint target so packages without
a compile target still wait for dependency compilation.
- Remove `lib/` from `tsc` outputs since it only writes CJS to `dist/`
- Remove `_api-extractor-temp` from api-extractor outputs to prevent
  conflicts between commonjs and esnext targets
- Add inputs/outputs to build:api-reports, build:docs, ci:build:docs,
  ci:build:api-reports, build:copy, and layerGeneration:gen targets
- Use directory glob `api-extractor/**` instead of flat `api-extractor*.json`
  for more precise input matching
- Add nx-mcp server configuration
Add inputs to check:exports, check:exports:bundle-release-tags,
check:release-tags, check:are-the-types-wrong, build:readme, and
build:manifest targets. Without explicit inputs Nx falls back to
hashing all project files, causing unnecessary cache misses when
unrelated files change.
- Add missing deps to `api` target: build:entrypoints:node10, tsc, build:esnext
- Add missing `build:esnext` dep to build:api-reports and ci:build:api-reports targets
- Add `build:entrypoints:node10` target default with proper inputs/outputs
- Add nx:run-commands executor for tsc/build:esnext to clean stale output (WIP)
- Add nx-clean-and-build.sh helper script for TS5055 composite mode workaround

The api target was missing deps added in 307eb07 (entrypoint restructuring),
causing @fluidframework/tree api-extractor failures and cascading type resolution
errors in downstream packages.
Remove nx:run-commands executor overrides from nx.json target defaults
and driver-definitions project.json. The upstream commit 0c9fe12
(split test build from library production) fixes the TS5055 stale output
issue by excluding src/test/ from production tsconfigs.

Also removes the nx-clean-and-build.sh helper script that is no longer
needed.
- Remove `^api` from eslint dependsOn (noop api targets on DDS packages
  don't block correctly) and add `^build:test` so upstream test type
  declarations are available when eslint runs
- Add missing dependsOn for check:exports subtasks (cjs:index, cjs:legacy,
  cjs:public, esm:index, esm:legacy, esm:public) which were racing ahead
  of tsc/build:esnext when run via concurrently
…-container

Add check:exports and eslint noop targets to migration-tools project.json,
and eslint noop target to separate-container project.json. These targets
were running against noop'd build outputs, causing failures.
Also add test -> test:unit dependency in nx.json.
Regenerated api-report files with updated union type ordering.
@github-actions
Copy link
Copy Markdown
Contributor

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output


> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  272202 links
    1863 destination URLs
    2108 URLs ignored
       0 warnings
       0 errors


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant