Skip to content

perf(cli): doctor's theme checks and the codemods' parser load postcss only when they read a stylesheet - #11925

Merged
josephfarina merged 2 commits into
mainfrom
speed/postcss-api-lazy
Nov 15, 2026
Merged

josephfarina merged 2 commits into
mainfrom
speed/postcss-api-lazy

Conversation

@josephfarina

Copy link
Copy Markdown
Contributor

Summary

Doctor's theme checks (api/doctor/theme-checks.mjs) and the codemods' parser (assets/codemods/parse.mjs) imported postcss at their top. The API's index reaches both, so every run that loads the API loaded all of postcss (28 CommonJS files) whether or not it read a stylesheet: doctor always did, and so does a run whose integration's codemods import the CLI's API, which a project's first lookup loads.

  • Both now use the shared first-use getter, postcss() from foundation/runtime/lazy-dependencies.mjs, so postcss loads only when a stylesheet is parsed.
  • postcss joins LAZY_PACKAGES, so test/lazy-dependencies.test.mjs now checks that importing the API loads none of it.
    • Its first row accepts a package whose ES module entry hands on what its CommonJS entry exports (postcss): require and import must give the same module.
    • Importing the API now loads no CommonJS package at all, so the scan is shown to see a load by one first use of postcss().
    • The row that checked only the theme build module is dropped; the API row covers it.
  • The page renderer, the CSS cutter, the theme editor and two codemod transforms still import postcss at their top. They are not on the API's import path.

Evidence

Wall time per call, a fresh process each, interleaved, n=11, median paired difference (95% CI), against main with the first postcss change:

Project Case main → change Difference
Core only doctor (two cases, warm) 238 → 232, 239 → 230 ms −8 [−14, −6], −10 [−11, −8]
One integration doctor (two cases, warm) 357 → 350, 364 → 353 ms −6 [−10, −4], −6 [−13, −5]
One integration first component call in a new home 1185 → 1168 ms −15 [−25, −8]
One integration first doctor call in a new home 1338 → 1333 ms −15 [−46, −3]

Every other case of the 51-case battery is within noise in both projects: weighted −0.3% (one integration) and −0.1% (core only). Identity: every timed run printed the same stdout and stderr, with the same exit code, as main.

Tests

  • test/lazy-dependencies.test.mjs: importing the API loads no LAZY_PACKAGES member, postcss now among them. The row fails with postcss imported at the top of theme-checks.mjs again.
  • api/upgrade, assets, api/doctor, foundation/doc-compiler (each first-use load site listed) and clients/cli/commands pass: 243 files.

Scope

No output, flag or JSON shape changes.

@vercel

vercel Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 15, 2026 9:53pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 15, 2026
@astracat-bot

astracat-bot Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 15, 2026, 9:56 PM UTC

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not finished on this head yet.

Moving doctor's theme checks and the codemods' parser to the shared postcss() getter leaves the CLI's output and API unchanged, and importing @astryxdesign/cli/api no longer loads postcss. The updated guard in test/lazy-dependencies.test.mjs fails if either module imports postcss at its top again. Nothing blocks; one optional fix:

  • The getter's doc comment (packages/cli/foundation/runtime/lazy-dependencies.mjs:74-76) lists the font stylesheet reader among the modules on the API's import path, but importing the API does not load it; the theme commands do.
Claims and files checked

Review mode: full; reason: no-earlier-review

  • Changeset: doctor starts about 6 to 10 ms sooner. Verified in mechanism: doctor in the sandbox app loads 28 fewer postcss files, and postcss takes about 15 ms to load here; the exact figure is the author's measurement and was not reproduced.
  • Changeset: a first lookup with an integration that imports the API is about 15 ms sooner. Verified in mechanism: contribution validation loads integration codemods, and importing the API no longer loads postcss; the figure was not reproduced.
  • Changeset: both modules loaded postcss as they loaded, so every API importer did. Verified: importing the API loads 41 CommonJS files on the base, 28 of them postcss, and none on the head.
  • Changeset: they now load postcss only when they read a stylesheet. Verified at theme-checks.mjs:469, :536 and parse.mjs:48.
  • Changeset and description: output does not change. Verified: doctor's output is identical, and 244 test files pass.
  • Description: postcss is 28 CommonJS files. Verified.
  • Description: doctor always loaded it. Verified: doctor.mjs imports the theme checks at load.
  • Description: both modules use the shared getter, and postcss joins LAZY_PACKAGES. Verified.
  • Description: the first test row accepts an ES module entry that hands on the CommonJS exports. Verified at lazy-dependencies.test.mjs:84-90.
  • Description: importing the API loads no CommonJS package, so one first use proves the scan. Verified at lazy-dependencies.test.mjs:154-171.
  • Description: the API row covers the dropped theme-build row. Verified: importing the API loads the theme build module.
  • Description: five other modules still import postcss at their top and are off the API's import path. Verified.
  • Description: the timing table. The author's measurement; not reproduced here.
  • Description: the guard fails when the theme checks import postcss at their top again. Verified by mutation, and also for the codemods' parser.
  • Description: the listed test folders pass. Verified: 244 files, with the lazy-dependency test itself.
  • Description: no output, flag or JSON shape changes. Verified.
  • File .changeset/postcss-api-on-first-use.md: clear.
  • File packages/cli/api/doctor/theme-checks.mjs: clear.
  • File packages/cli/assets/codemods/parse.mjs: clear.
  • File packages/cli/foundation/runtime/lazy-dependencies.mjs: non-blocking doc-comment note, lines 74-76.
  • File packages/cli/test/lazy-dependencies.test.mjs: clear.

Automated review (maintainer link)

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

🔎 Preview · 53dedc1

Storybook · Sandbox · built from this PR's head

Package size: @astryxdesign/cli 4.84 MB packed (+25 B); no new dependencies.

Not run on this PR: add ci:run-visual for Visual, ci:run-a11y for Accessibility, ci:run-rtl for RTL.

Current run: CI concluded cancelled; parts of this report may be missing.


Generated by PR Enrichment workflow | View full report

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI's heavy jobs have not run on this head yet, because its admission job found no room under the CI ceiling ("CI is full"); re-run the CI workflow so they run.

Doctor's theme checks and the codemods' parser now load postcss through the shared postcss() getter, so importing @astryxdesign/cli/api no longer loads postcss, and the CLI's output and API are unchanged. The reworded doc comment on the getter fixes the earlier note: it no longer places the font stylesheet reader on the API's import path. Nothing blocks.

Claims and files checked

Review mode: incremental; reason: none

  • Changed rules (0): none.
  • Changeset: doctor starts about 6 to 10 ms sooner. Verified in mechanism: doctor no longer loads postcss at start, and postcss takes about 15 ms to load; the exact figure is the author's measurement and was not reproduced.
  • Changeset: a first lookup with an integration that imports the API is about 15 ms sooner. Verified in mechanism: importing the API no longer loads postcss; the figure was not reproduced.
  • Changeset: both modules loaded postcss as they loaded, so every API importer did. Verified: importing the API loads 41 CommonJS files on the base, 28 of them postcss, and none on the head.
  • Changeset: they now load postcss only when they read a stylesheet. Verified at theme-checks.mjs:469, :536 and parse.mjs:48.
  • Changeset and description: output does not change. Verified: doctor's output is identical, and 244 test files pass.
  • Description: postcss is 28 CommonJS files. Verified.
  • Description: doctor always loaded it. Verified: doctor.mjs imports the theme checks at load.
  • Description: both modules use the shared getter, and postcss joins LAZY_PACKAGES. Verified at theme-checks.mjs:12, parse.mjs:15 and lazy-dependencies.mjs:93.
  • Description: the first test row accepts an ES module entry that hands on the CommonJS exports. Verified at lazy-dependencies.test.mjs:78-91.
  • Description: importing the API loads no CommonJS package, so one first use proves the scan sees a load. Verified at lazy-dependencies.test.mjs:140-173.
  • Description: the API row covers the dropped theme-build row. Verified: importing the API loads the theme build module.
  • Description: five other modules still import postcss at their top and are off the API's import path. Verified.
  • Description: the timing table and the battery result. The author's measurement; not reproduced.
  • Description: every timed run printed the same output as main. The author's measurement; doctor's identical output was checked separately.
  • Description: the guard fails when the theme checks import postcss at their top again. Verified by mutation.
  • Description: the listed test folders pass. Verified: 244 files, with the lazy-dependency test itself.
  • Description: no output, flag or JSON shape changes. Verified.
  • File .changeset/postcss-api-on-first-use.md: clear.
  • File packages/cli/api/doctor/theme-checks.mjs: clear.
  • File packages/cli/assets/codemods/parse.mjs: clear.
  • File packages/cli/foundation/runtime/lazy-dependencies.mjs: clear; the earlier doc-comment note is fixed.
  • File packages/cli/test/lazy-dependencies.test.mjs: clear.

Automated review (maintainer link)

@josephfarina
josephfarina merged commit dc58f19 into main Nov 15, 2026
133 of 139 checks passed
@github-actions
github-actions Bot deleted the speed/postcss-api-lazy branch November 16, 2026 06:04

This branch was successfully deployed

1 active deployment
Preview — 53dedc11 Deployed Nov 15, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant