Skip to content

[experimental] export: compile StyleX in a package that ships StyleX source - #12869

Draft
josephfarina wants to merge 1 commit into
mainfrom
josephfarina/rl-export-package-stylex
Draft

josephfarina wants to merge 1 commit into
mainfrom
josephfarina/rl-export-package-stylex

Conversation

@josephfarina

@josephfarina josephfarina commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

What users see

A page that uses a component from a package that ships StyleX source (not compiled StyleX) now exports. Before, a component that calls stylex.keyframes (or stylex.defineVars, stylex.createTheme, stylex.firstThatWorks) failed the export with:

The page threw while rendering: Unexpected 'stylex.keyframes' call at runtime. Styles must be compiled by '@stylexjs/babel-plugin'.

Now the package's styles compile the way an app's build compiles them, and its animations run in the exported file.

How

astryx experimental export compiled StyleX only in the page's own files. A package file (installed in node_modules, or a workspace package linked in from outside the project) now compiles with the StyleX compiler too, when it holds a StyleX build-time call:

  • Only the StyleX plugin runs on it (no page plugins, nothing recorded as page text), with the page's class-name prefix. In an app, third-party source compiles in the product pass with the product prefix, so the page prefix is the match, and the classes never share a name with Core's.
  • The compiled code is used only when StyleX finds rules in the file. Every other package file, compiled StyleX and Core included, stays byte for byte as it ships.
  • The page's script: the bundler calls back only for the package files known to hold StyleX source (a filter of those exact files), so every other package, Core included, stays with the bundler. After the script is built, each package file it holds that no render checked yet is checked the same way; when one holds StyleX source, the script is built once more with it compiled. That is the only extra cost, and only a page that needs it pays it. It cannot loop: compiling only removes StyleX calls, so the second build holds no file the first did not, and the script is built at most twice. That covers every file only the browser loads: a package a click imports, a file that re-exports one, a page module only a click loads, and a package's own lazy import.

Tests

packages/cli/api/render/render.package-stylex.test.mjs (new): a package that ships source with a keyframes marquee, and a lazily imported pulsing badge in a second file, from node_modules and from a linked workspace folder outside the project; and four packages the first paint never uses that a click loads: the badge's file directly, a file that re-exports it, a page module that imports it, and a package file that imports it lazily.

  • Server render: the marquee's classes carry the page prefix and name a keyframes rule in the file's stylesheet.
  • The page's script, run in a DOM: no error, and the lazy badge's classes name a keyframes rule in the stylesheet.
  • Each click case draws its badge with its keyframes animation and no error.
  • With the check after the build turned off, the lazy badge and all four click cases fail.
  • A package whose browser field maps a file to false exports (the check after the build skips the file esbuild leaves out); without that skip it fails with ENOENT.
  • Control: a package that ships compiled StyleX keeps its class names and adds no rule, also when the page loads it only through import(); a page with only that package compiles no package file.
  • Base: the node_modules and workspace cases fail with the runtime error above; with the change all 13 pass.

Real browser (Chromium, the exported file): both animations report running, the marquee's transform moves, no page errors.

Size and speed: an export of a Core-only page (the dashboard template) is byte-identical with and without the change (2,028,571 bytes both, measured before the rebase onto current main), and its time is within noise (median of 5 alternating runs: 3.41 s before, 3.42 s after).

A page that loads a Core subpath through import() exports byte-identical with and without the change (541,410 bytes both), in the same time (median of 5 alternating runs: 1.06 s before, 1.06 s after).

A page whose only source-StyleX package loads on a click pays the one extra build: median of 5 alternating runs, 0.91 s before (that file throws the runtime error on the click) and 1.08 s after; the file grows from 238,939 to 253,406 bytes, for the package's compiled styles.

@vercel

vercel Bot commented Nov 19, 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 19, 2026 9:28pm UTC

Request Review

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

astracat-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 19, 2026, 9:50 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.

Changes requested: two fixes so that a lazily imported file of a StyleX-source package carries its styles as the release note says.

  • packageFolderOf (packages/cli/foundation/render/page-worker.mjs:1285) keys the bundler's filter on the nearest package.json, so in a package with a nested marker such as src/package.json a file loaded only through import() from another folder ships uncompiled and throws "Unexpected 'stylex.keyframes' call at runtime" in the exported file; walk up to the package root (the nearest package.json with a name) and add that layout to the test.
  • The changeset's "A file of the package that the page loads lazily carries its styles too" does not hold for a component the page reaches only through import() from a package its first paint never uses, which still throws the same error; narrow the sentence to a package the first paint already uses, or extend the filter so it holds.

The rest checks out: the new tests fail on the base with that error and pass here, a stylex.create-only package and a dual-format package export too, a Core-only page's file is byte-identical, and in Chromium both animations run. Non-blocking: the description says "(numbers below)" but gives none, and the export docs (render.doc.mjs, export-pages.doc.mjs) still say only the page's own StyleX compiles. The head commit's message carries [skip ci], so CI will not run at this head; leave it out of the next push.

Claims and files checked

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

  • Changeset: export compiles StyleX source shipped in a package, as an app's build does: verified (page-worker.mjs:1246-1277, :1341-1365; the new test).
  • Changeset: such a component, installed or linked in from a workspace, used to fail with the keyframes runtime error: verified (the new test fails on the base for both).
  • Changeset: its styles use the page's class prefix, so no class is shared with Core: verified (prefix p, page-worker.mjs:96, :1217; the test asserts it).
  • Changeset: its animations run in the exported file: verified (keyframes in the stylesheet; Chromium reports both animations running).
  • Changeset: a lazily loaded file of the package carries its styles: false for a package the first paint never uses and for a file outside a nested package.json folder (the two findings above).
  • Changeset: a package that ships compiled StyleX stays as it ships: verified (the test's control; compiled output is kept only when rules exist).
  • Description: the base's error text: verified (the new test on the base).
  • Description: only the StyleX plugin runs on a package file, with the page prefix, and nothing is recorded as page text: verified (page-worker.mjs:1253-1266).
  • Description: an app compiles third-party source in its product pass with the product prefix: verified against the build package's documentation.
  • Description: every other package file, compiled StyleX and Core included, stays byte for byte: verified (two Core files take a pass that finds no rules; their output is unchanged).
  • Description: the bundler calls back only for files inside the packages the server render found: verified (client-bundle.mjs:661-668).
  • Description: a file of such a package that only the browser loads compiles and carries its styles: verified when the package root holds the only package.json; false with a nested one (first finding).
  • Description: the tests (server render, script in a DOM, compiled control, base failures, all 7 pass): verified.
  • Description: in a real browser both animations run, the marquee moves, and the page logs no error: verified in Chromium.
  • Description: a Core-only page's export is byte-identical and its time within noise: verified (dashboard template: identical file; renders within 1% in a second interleaved round); the promised numbers are missing.
  • File .changeset/export-package-stylex-source.md: blocking (the lazy sentence).
  • File packages/cli/api/render/render.package-stylex.test.mjs: clear.
  • File packages/cli/foundation/render/client-bundle.mjs: clear (its filter takes the folders the first finding narrows).
  • File packages/cli/foundation/render/page-worker.mjs: blocking (packageFolderOf); non-blocking (the build-call test also matches comments).

Automated review (maintainer link)

@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.

Changes requested: two fixes so that the release note's lazy-load promise holds and the nested-marker fix has a test that guards it.

  • The changeset's "A file of the package that the page loads lazily carries its styles too" (.changeset/export-package-stylex-source.md:5) still fails, because checkLazyImports (packages/cli/foundation/render/page-worker.mjs:1329) checks only the one file an import() resolves to, and only in modules the server render loaded, so a click that runs import('kit') on a package whose entry re-exports its StyleX components, or import('./Panel') where Panel imports such a package, throws "Unexpected 'stylex.keyframes' call at runtime" in the exported file; check the files the package's entry reaches and the imports of modules only the browser loads, or narrow the sentence to what holds.
  • All 9 cases in render.package-stylex.test.mjs still pass with packageFolderOf reverted to "nearest package.json", because the page's own import('marquee-kit/badge') records the package root anyway, so make the marker fixture reach its outside file through the package's own relative import(), which makes the test fail without the fix as the description says it does.

The rest checks out: the new tests fail on the base with the runtime error and pass here, the nested package.json fix works for a package that lazily imports its own file, a Core-only page and a page that lazily imports a Core subpath export byte-identical files in the same time, and in Chromium the marquee and the directly imported badge animate. Non-blocking: the head commits carry [skip ci], so no build or test job has run at this head.

Claims and files checked

Review mode: incremental; reason: none

  • Changeset: export compiles StyleX that a package ships as source, as an app's build does. Verified (page-worker.mjs:1259-1290; the new test).
  • Changeset: such a component, installed or linked from a workspace, used to fail with the runtime error. Verified (the new test fails on the base; stylex.defineVars and stylex.createTheme are in the build-call test at :1242).
  • Changeset: its styles take the page's class prefix, so no class is shared with Core. Verified (prefix p, :96, :1230; the test asserts it).
  • Changeset: its animations run in the exported file. Verified (Chromium reports the animations running, and the marquee's transform moves).
  • Changeset: a file of the package that the page loads lazily carries its styles. False for a barrel entry, a lazily loaded local module, and an import() inside one (first finding).
  • Changeset: a package that ships compiled StyleX stays as it ships. Verified (the test's controls; output is kept only when StyleX emits rules, :1281).
  • Description: the base's error text. Verified (the new test on the base).
  • Description: only the StyleX plugin runs on a package file, with the page prefix, and nothing is recorded as page text. Verified (:1266-1279).
  • Description: an app compiles third-party source in its product pass with the product prefix. Verified (packages/build/README.md:248).
  • Description: every other package file, compiled StyleX and Core included, stays byte for byte as it ships. Verified (a Core-only export is identical with and without the change).
  • Description: the bundler calls back only for files of packages the server render found, or whose import() file holds StyleX source. Verified (client-bundle.mjs:661-669, page-worker.mjs:1329-1336). "The page's own modules" covers only the modules the server render loaded (first finding).
  • Description: a file of such a package that only the browser loads, through import(), compiles and carries its styles. Verified (a direct subpath import(), and a package's own relative import() across a nested marker).
  • Description: the listed test cases (server render, script in a DOM, click import, compiled controls). Verified (9 of 9 pass here).
  • Description: a nested marker keeps the rest of the package covered, and the test fails without that rule. The rule is verified; the test claim is false (second finding).
  • Description: each import() of a package gets the same check, and the test fails without it. Verified (with the check disabled, the click case fails).
  • Description: the base fails the node_modules and workspace cases with the runtime error, and all 9 pass with the change. Verified.
  • Description: in Chromium, both animations run, the marquee moves, and the page logs no error. Verified on an equivalent export.
  • Description: a Core-only page exports a byte-identical file in the same time. Verified (dashboard template: identical file, median 3.26 s against 3.30 s).
  • Description: a page that loads a Core subpath through import() exports a byte-identical file in the same time. Verified (identical file, 0.83 s both).
  • File .changeset/export-package-stylex-source.md: blocking (the lazy-load sentence).
  • File packages/cli/api/render/render.doc.mjs: clear.
  • File packages/cli/api/render/render.package-stylex.test.mjs: blocking (the marker case does not guard the fix).
  • File packages/cli/assets/docs/tree/export-pages.doc.mjs: clear.
  • File packages/cli/foundation/render/client-bundle.mjs: clear.
  • File packages/cli/foundation/render/page-worker.mjs: blocking (the scope of checkLazyImports).

Automated review (maintainer link)

@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.

Changes requested: the new check after the script build refuses some pages that exported before, and the branch needs main merged in.

  • A page whose script bundles a package that maps one of its files to false in its browser field is now refused with "ENOENT: no such file or directory", because the list of bundled files (client-bundle.mjs lines 759-762) keeps esbuild's (disabled): inputs and checkScriptFiles (page-worker.mjs line 1289) reads them as files; skip those names, skip any path that does not exist, and add a test with such a package.
  • Regression: the branch now conflicts with main in render.doc.mjs, export-pages.doc.mjs, client-bundle.mjs and page-worker.mjs, and on main the export refuses a page that uses no Astryx (ERR_RENDER_NOT_ASTRYX), which is every page in render.package-stylex.test.mjs, so after merging give each fixture page an Astryx import so the tests exercise pages the command writes.

The changeset's lazy-load sentence now holds: the four click layouts and the lazy badge draw with their styles, and they fail on the base and without the rebuild.

Claims and files checked

Review mode: incremental; reason: none

  • changed rules (0): none
  • Claim: a source package's keyframes, vars, theme or fallback call used to fail export with StyleX's runtime error: verified (the new test fails that way on the base).
  • Claim: the package's styles now compile as an app's build does, with the page's class prefix, and its animations run: verified (12 of 12 tests pass; keyframes and prefixed classes in the file).
  • Claim: only the StyleX plugin runs on a package file, and its output is used only when StyleX finds rules: verified (page-worker.mjs 1209-1222, 1246-1276).
  • Claim: every other package file, compiled StyleX and Core included, stays as it ships, and only a page that needs it pays an extra cost: false for a page that bundles a browser-disabled file, which is now refused; every page also pays a scan of its script's package files.
  • Claim: the bundler calls back only for the exact files that hold StyleX source: verified (client-bundle.mjs 661-667).
  • Claim: after the build, unchecked package files are checked and the script is built at most once more: verified (page-worker.mjs 1285-1292, 2017-2021).
  • Claim: this covers a click import, a re-export, a page module and a package's own lazy import: verified (four click tests pass on the head, fail on the base).
  • Claim: with the check turned off, the lazy badge and all four click cases fail: verified (6 of 12 fail).
  • Claim: on the base the source-package cases fail with the runtime error, and all 12 pass with the change: verified.
  • Claim: a compiled-StyleX package keeps its classes and adds no rule, also through import(): verified (both controls pass on base and head).
  • Claim: Chromium runs both animations with no page errors: consistent with the code; the first-paint path is unchanged since it was captured at the previous head.
  • Claim: Core-only and Core-subpath pages export byte-identical, and the click page grows by the package's styles: consistent with the code (no filter and no rebuild without a StyleX-source file; Core's files hold no StyleX build call outside comments); sizes not re-measured.
  • Changeset: compiles a StyleX-source package's styles with the page prefix, never sharing a class with Core's: verified (prefix p; Core's classes use x).
  • Changeset: a lazily loaded file of the package carries its styles: verified.
  • Changeset: a package that ships compiled StyleX stays as it ships: verified.
  • File .changeset/export-package-stylex-source.md: clear.
  • File packages/cli/api/render/render.doc.mjs: clear.
  • File packages/cli/assets/docs/tree/export-pages.doc.mjs: clear.
  • File packages/cli/api/render/render.package-stylex.test.mjs: finding (pages without Astryx, refused on main).
  • File packages/cli/foundation/render/client-bundle.mjs: finding ((disabled): inputs kept as files).
  • File packages/cli/foundation/render/page-worker.mjs: finding (reads those inputs and fails the export).

Automated review (maintainer link)

A package component that uses stylex.keyframes (or defineVars, createTheme,
firstThatWorks) threw "Unexpected 'stylex.keyframes' call at runtime" in an
export, because only the page's own files went through the StyleX compiler.
A package file (installed, or a workspace package linked in) that holds a
StyleX build-time call now compiles with StyleX only, with the page's class
prefix, for the server render and the page's script. The script's bundler
calls back only for the files that hold StyleX source. After the script is
built, each package file it holds that no render checked yet is checked the
same way, and the script is built once more when one holds StyleX source,
so a file only the browser loads carries its styles too. A file whose
compile finds no rules, such as compiled StyleX, stays as it ships.
@josephfarina
josephfarina force-pushed the josephfarina/rl-export-package-stylex branch from 39d4d68 to 0ae6c3a Compare November 19, 2026 21:11
@github-actions

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@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 run on this head yet, because the pull request is a draft; it runs once the pull request is marked ready for review.

Both earlier findings are fixed: a page that bundles a package file mapped to false in its browser field exports again, and every test page now imports Core's stylesheet, so the export's Astryx-only rule on main lets it through. Two optional follow-ups: route the new metafile filter in client-bundle.mjs through the existing inputFile so both agree on (disabled): names, and add a defineVars/createTheme case to the test, since the changeset names them.

Claims and files checked

Review mode: full; reason: rebase

  • Claim: a source package's keyframes, variables, theme or fallback call used to fail export with StyleX's runtime error: verified (the new test fails that way on the base; a variables probe fails with the same error).
  • Claim: the package's styles now compile as an app's build compiles them, and its animations run in the file: verified (13 of 13 tests pass; Chromium shows the animation running with no page errors).
  • Claim: an installed package file, or one of a workspace package linked from outside the project, compiles with StyleX when it holds a build-time call: verified (page-worker.mjs 1660-1690; both fixture layouts pass).
  • Claim: only the StyleX plugin runs on it, with the page's prefix, and nothing is recorded as page text: verified (page-worker.mjs 1667-1680).
  • Claim: an app compiles third-party source in its product pass, so the page prefix is the match: verified (@astryxdesign/build treats every file outside its library patterns as product).
  • Claim: the compiled code is used only when StyleX finds rules, and every other package file, compiled StyleX and Core included, stays as it ships: verified (page-worker.mjs 1682-1686; both compiled-StyleX controls pass; a Core-only page exports byte-identical).
  • Claim: the bundler calls back only for the exact files that hold StyleX source: verified (client-bundle.mjs 817-823).
  • Claim: after the build, unchecked package files are checked and the script is built at most once more, and only a page that needs it pays: verified (page-worker.mjs 1699-1707 and 2482-2486; a Core-only page exports in the same time).
  • Claim: this covers a click import, a re-export, a page module and a package's own lazy import: verified (the four click tests pass on the head and fail on the base).
  • Claim: with the check after the build turned off, the lazy badge and all four click cases fail: verified (6 of 13 fail).
  • Claim: a package that maps a file to false in its browser field exports, and without the skip it fails with ENOENT: verified (passes on the head; fails with ENOENT once both the name filter and the missing-file skip are removed; either one alone still passes).
  • Claim: a compiled-StyleX package keeps its classes and adds no rule, also through import(), and a compiled-only page compiles no package file: verified (both controls pass on the base and the head).
  • Claim: on the base the source-package cases fail with the runtime error, and all 13 pass with the change: verified.
  • Claim: Core-only and Core-subpath pages export byte-identical in the same time: verified on a Core page that loads a Core subpath on a click (identical bytes, same time); the dashboard numbers were not re-measured.
  • Claim: a page whose only StyleX-source package loads on a click pays one extra build and grows by that package's styles: consistent with the code; not re-measured.
  • Changeset: the export compiles a StyleX-source package's styles as an app's build does: verified.
  • Changeset: keyframes, defineVars, createTheme and firstThatWorks used to fail with the runtime error: verified for keyframes and defineVars on the base; all four compile on the head.
  • Changeset: the styles take the page's class prefix and never share a class with Core's: verified (prefix p; Core's classes use x).
  • Changeset: a lazily loaded file of the package carries its styles, and its animations run: verified.
  • Changeset: a package that ships compiled StyleX stays as it ships: verified.
  • File .changeset/export-package-stylex-source.md: clear.
  • File packages/cli/api/render/render.doc.mjs: clear.
  • File packages/cli/assets/docs/tree/export-pages.doc.mjs: clear.
  • File packages/cli/api/render/render.package-stylex.test.mjs: clear (non-blocking: no defineVars/createTheme case).
  • File packages/cli/foundation/render/client-bundle.mjs: clear (non-blocking: a second metafile-name parser beside inputFile).
  • File packages/cli/foundation/render/page-worker.mjs: clear.

Automated review (maintainer link)

// or `(disabled):` for a file a package's `browser` field maps to false.
const files = kept
.map(([name]) => name)
.filter(name => !/^[^\\/]+:/.test(name) || /^[a-z]:[\\/]/i.test(name))

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.

Non-blocking: this is a second parser of metafile names beside inputFile (line 953), and the two already differ: this one drops (disabled): names, while inputFile still resolves them to a path that does not exist. Routing both through one helper would keep the namespace and (disabled): rules in one place.

This branch was successfully deployed

1 active deployment
Preview — 0ae6c3a1 Deployed Nov 19, 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