Skip to content

WP Build: Use one Sass compiler process for the whole build - #85257

Closed
sirreal wants to merge 3 commits into
trunkfrom
build/shared-sass-compiler
Closed

sirreal wants to merge 3 commits into
trunkfrom
build/shared-sass-compiler

Conversation

@sirreal

@sirreal sirreal commented Oct 21, 2026

Copy link
Copy Markdown
Member

What?

wp-build now compiles Sass through one Dart Sass process for the whole run, instead of starting two in every esbuild build that handles styles.

Why?

esbuild-sass-plugin with embedded: true calls sass-embedded's initAsyncCompiler() in each plugin setup(), so every esbuild.build() that includes the plugin starts a Dart Sass process and stops it when the build ends. wp-build adds two plugin instances to each transpile (CJS and ESM), route and widget build, and one to each style entry point, including builds of packages that have no styles.

A full npm run build on trunk starts 722 Dart Sass processes, up to 169 at once (counted by logging every spawn). Phase 3 runs 56 at once, four for each route with a content bundle, while the process tree's memory use is at its highest in local samples. On macOS arm64 the Dart Sass processes reached 864 MB RSS together in 1-second samples; with this change the single process peaks at 89 MB.

How?

  • lib/sass-plugin.mjs is a small esbuild plugin over one AsyncCompiler, started on the first Sass file. AsyncCompiler runs concurrent compilations over one process. The plugin calls compileAsync() with the existing importers and loadPaths, reads .css files as they are without Sass, as esbuild-sass-plugin did, and passes the CSS to the existing transform callbacks.
  • main() disposes the compiler after a one-off build, because its child process would otherwise keep Node.js running. Watch mode keeps it for rebuilds.
  • The esbuild-sass-plugin dependency is removed.

Compatibility: imports now resolve by Sass's own rules (relative to the importing file, then loadPaths, and pkg: URLs through NodePackageImporter). esbuild-sass-plugin had its own resolver, which also accepted webpack-style ~package/path imports; those no longer resolve. Gutenberg has none. Sass warnings are printed by Sass instead of being reported as esbuild warnings; the build has none today.

The output of npm run build is byte-identical to trunk: diff -r of build/ and packages/*/build, build-module, build-style and build-wp (22,528 files) reports no difference.

The DROPME: commit disables every CI job except the E2E Build job, so its time can be compared with recent runs. It is for measurement only and will be dropped before merge. Timings will follow in a comment.

Testing Instructions

  1. Run npm run build on trunk and on this branch, and compare build/ and packages/*/build* with diff -r. They are identical.
  2. While the build runs, pgrep -f 'sass.snapshot --embedded' | wc -l shows at most 1.
  3. Run npm run dev, change a declaration in packages/block-library/src/paragraph/style.scss, and check that packages/block-library/build-style/paragraph/style.css is rebuilt with it. Stop with Ctrl+C; no sass.snapshot --embedded process remains.
  4. Run npm run test:unit -- packages/wp-build/lib/test/sass-plugin.js.

Testing Instructions for Keyboard

Not applicable: no UI change.

Use of AI Tools

AI assistance: Yes
Tools: Claude Code
Model: Claude Opus 5.5
Used for: Implementation, tests, measurements and this description.

esbuild-sass-plugin starts a Dart Sass process in every esbuild build that
includes it, and wp-build adds two instances to each transpile, route and
widget build plus one to each style entry point. A full Gutenberg build
started 722 Dart Sass processes, up to 169 at once.

Replace it with a small plugin that compiles through one sass-embedded
AsyncCompiler, started on first use and disposed after a one-off build.
Watch mode keeps it for later rebuilds. Plain CSS files are still read
as they are, without Sass.

The build output is byte-identical (22,528 files under build/ and
packages/*/build{,-module,-style,-wp}).
Sets `if: false` on every job of the workflows that run on pull_request, except the detect-relevant-changes and build jobs of end2end-test.yml, so only the E2E Build job runs while its time is measured. Drop this commit before merging.
@sirreal sirreal added the [Type] Build Tooling Issues or PRs related to build tooling label Oct 21, 2026
@github-actions

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground

@github-actions github-actions Bot added the [Package] wp-build /packages/wp-build label Oct 21, 2026
@sirreal sirreal closed this Oct 21, 2026
@sirreal
sirreal deleted the build/shared-sass-compiler branch October 21, 2026 09:16
@sirreal

sirreal commented Oct 21, 2026

Copy link
Copy Markdown
Member Author

Build job timings on ubuntu-24.04. This PR: the Build job of run 39552487064, attempts 1 to 3 (attempts 2 and 3 rerun the Build job). Upstream: the 15 most recent successful E2E Build jobs on other PRs and trunk, started between 08:23 and 10:59 UTC today, excluding #85252. Phase times are the gaps between the timestamps of the Phase N log lines; npm run build and wp-build are the totals the build prints. Median, with the range in parentheses.

Upstream, 15 jobs This PR, 3 jobs
Build job (s) 143 (124–232) 147 (125–219)
npm run build (s) 78 (71–107) 69 (64–94)
wp-build (s) 60.1 (54.4–82.2) 52.1 (48.2–70.8)
Phase 1, transpile (s) 21.0 (18.9–29.0) 15.9 (14.4–22.0)
Phase 2, bundle (s) 21.9 (19.4–30.7) 20.4 (19.3–28.1)
Phase 3, routes (s) 12.0 (10.2–15.4) 10.4 (9.9–14.0)
Phase 4, widgets (s) 5.7 (5.1–7.5) 5.4 (4.6–6.7)

Runner speed varies more than this change. Phase 2 compiles no Sass, so its time indicates the runner: over the 40 most recent upstream jobs it took 18.7–23.9 s on 18 and 26.7–31.0 s on 22. Two of this PR's runs fell in the first group and one in the second. Grouped that way:

Upstream, Phase 2 < 24 s, 18 jobs This PR, 2 jobs Upstream, Phase 2 ≥ 24 s, 22 jobs This PR, 1 job
Build job (s) 132 (120–171) 125, 147 175 (166–232) 219
npm run build (s) 75 (66–87) 64, 69 104.5 (96–109) 94
wp-build (s) 57.1 (51.1–65.5) 48.2, 52.1 79.9 (72.2–83.3) 70.8
Phase 1, transpile (s) 19.6 (17.7–23.6) 14.4, 15.9 27.3 (24.2–29.3) 22.0
Phase 2, bundle (s) 21.0 (18.7–23.9) 19.3, 20.4 29.6 (26.7–31.0) 28.1
Phase 3, routes (s) 11.1 (9.7–12.3) 9.9, 10.4 15.3 (14.6–15.6) 14.0
Phase 4, widgets (s) 5.5 (4.4–5.8) 4.6, 5.4 7.4 (6.6–8.1) 6.7

As a fraction of Phase 2 in the same job, Phase 1 took 0.93 (0.88–0.99) upstream and 0.78 (0.75–0.78) here; Phases 3 and 4 together took 0.78 (0.73–0.82) upstream and 0.75 (0.74–0.77) here. The gain is in Phase 1, about 4–5 s; Phases 3 and 4 gain about 1–2 s. The Build job total also includes the dependency install (24–72 s in these three runs) and the artifact upload, which vary more than the build does.

Local, macOS arm64, three npm run build runs each. Dart Sass processes are counted by logging every spawn; RSS is sampled with ps once a second.

trunk This PR
Dart Sass processes started 722 1
Most Dart Sass processes at once 169 1
Dart Sass RSS, peak sample 864–1,161 MB 88–89 MB
wp-build process tree RSS, peak sample 7.6–9.2 GB 6.8–7.2 GB
Phase 1 (s) 12.5–13.3 11.3–11.8
wp-build (s) 22.0–26.2 22.2–24.4

The machine was running other work, so the local totals do not separate. The tree's RSS rises to 6–7 GB during Phase 2, which compiles no Sass.

For comparison, the pure JS sass package (embedded: false, which also needs sass's own NodePackageImporter) gives byte-identical output with no child process; in two local runs wp-build took 21.8 and 22.2 s and the tree peaked at 7.9 and 8.3 GB.

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

Labels

[Package] wp-build /packages/wp-build [Type] Build Tooling Issues or PRs related to build tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant