Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/export-package-stylex-source.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/cli': patch
---

[experimental] `astryx experimental export` compiles the StyleX in a package that ships StyleX source, as an app's build does. A component from such a package, installed or linked in from a workspace, that uses `stylex.keyframes`, `stylex.defineVars`, `stylex.createTheme` or `stylex.firstThatWorks` used to fail with "Unexpected 'stylex.keyframes' call at runtime". Its styles now compile with the page's own class-name prefix, so they never share a class with Core's, and its animations run in the exported file. A file of the package that the page loads lazily carries its styles too. A package that ships compiled StyleX stays as it ships.
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved

@josephfarina
2 changes: 1 addition & 1 deletion packages/cli/api/render/render.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ export const doc = {
summary:
'Render a page to one self-contained HTML file, or turn a rendered file back into a page.',
description:
"Renders the page module's default export on the server with the project's own React and Astryx components (outside a project, with the Astryx, React and StyleX the CLI runs with, and, when a tool runs the CLI through its host entry, the packages the `package.json` beside that CLI lists in `dependencies` or `optionalDependencies`), and writes ONE HTML file that is the page as a live app and needs nothing beside it: the page's own StyleX styles are compiled, Core's stylesheets are cut to the rules the page can use (layer order, custom properties and keyframes kept), local images become data: URIs, the page's source is embedded so it can be given back exactly, and the page's own script follows it inline: the page's modules and the packages they use, bundled for the browser by esbuild (a dependency of the CLI that only this function loads). The file paints its markup first, then the script draws the live page over it, so state, effects and event handlers work: popovers, menus, dialogs, tabs and forms behave as in the app. An image the page names by an `https` address is fetched once while the page renders, with no cookies or credentials, only when it is an image of up to 8 MB, within a time limit for each image and one for all of them, and the file carries it; a failure leaves the address and warns, except that an address the page's code holds that counts as an image only by a name (an object's `src`, `imageUploadUrl`) is listed, and its fetch adds no warning, when its answer is another type. The file loads nothing from the network and the render adds no `eval`, so it works in a sandboxed frame that allows scripts under a policy that allows inline scripts, and its colors follow the viewer's light or dark scheme, unless the page's root theme draws in one mode by the stylesheets the page imports (a built theme's compiled stylesheet, or the page's own CSS), which the file keeps. A page whose script cannot be built for the browser (a module it loads needs Node, say) is refused. A page is refused with ERR_RENDER_COMPILE naming the file, the line, the module and the missing name, as a build refuses it, when it imports a name that one of its own modules, a StyleX variables module (`.stylex`) or an `@astryxdesign/*` package does not export, draws a member (`<Name.Member>`) such an export lacks, or imports any package subpath the package does not export (a named, default or side-effect import). A name another package does not export is refused only when the page's script is built: a page that draws or calls it as it renders fails with ERR_RENDER_FAILED first. Not checked: type imports, a name the page never uses as a value, a default import from a module that exists, a named import from one of the page's own CommonJS modules (a bundler reads those by interop), and a name the page imports through a TypeScript module that only re-exports it with a plain `export {…}` (such a page fails with ERR_RENDER_FAILED if it draws or calls the name as it renders). After writing, the render checks the file it wrote: what its markup and stylesheets load from outside the file, and whether `--reverse` gives back every carried file exactly. It reports a failed check by name, never blocks the write, and names the one file to share when the file stands alone. It says what the file's size is made of: the script, the CSS, the markup (with its inlined images) and the embedded source, each in bytes (`scriptBytes`, `cssBytes`, `markupBytes`, `sourceBytes`), and when the script is most of it. Warnings name anything that may differ from what the author meant, such as a component that did not render the text it was given. The file opens with a plain note for its next reader, a person or an agent: the CLI version and render format that made it, the page's path, the files it carries, the packages and versions it rendered with, and the exact commands that give the page back and render it again; the embedded source records the same facts and the markup as rendered. Each file the page uses that a render cannot carry is named on the note's 'Not carried' line and in `notCarried` (the JSON result and the text output), and its warning says why; the note then no longer says the page comes back exactly. A file left out because its name reads as a tool's configuration gets the `not-carried` warning, which says what carries it. With `reverse` (the way back, or unrender), it writes the embedded source back byte for byte, and only the files a render embeds: the page and the local modules, stylesheets, JSON files and images it imports, into a new folder; it also reports the render format, the CLI version and packages that rendered the file, and whether someone changed the markup after the render, naming each run of text that changed and where the old text sits in the restored source (the restored files stay the page as rendered); a file with Astryx markup but no embedded source is rebuilt from its component class names and data attributes (text and layout only); any other file is refused. Experimental: it may change or be removed in a patch release.",
"Renders the page module's default export on the server with the project's own React and Astryx components (outside a project, with the Astryx, React and StyleX the CLI runs with, and, when a tool runs the CLI through its host entry, the packages the `package.json` beside that CLI lists in `dependencies` or `optionalDependencies`), and writes ONE HTML file that is the page as a live app and needs nothing beside it: the page's own StyleX styles are compiled, and so are those of a package that ships StyleX source instead of compiled styles (with the page's class-name prefix, so they never share a class with Core's), Core's stylesheets are cut to the rules the page can use (layer order, custom properties and keyframes kept), local images become data: URIs, the page's source is embedded so it can be given back exactly, and the page's own script follows it inline: the page's modules and the packages they use, bundled for the browser by esbuild (a dependency of the CLI that only this function loads). The file paints its markup first, then the script draws the live page over it, so state, effects and event handlers work: popovers, menus, dialogs, tabs and forms behave as in the app. An image the page names by an `https` address is fetched once while the page renders, with no cookies or credentials, only when it is an image of up to 8 MB, within a time limit for each image and one for all of them, and the file carries it; a failure leaves the address and warns, except that an address the page's code holds that counts as an image only by a name (an object's `src`, `imageUploadUrl`) is listed, and its fetch adds no warning, when its answer is another type. The file loads nothing from the network and the render adds no `eval`, so it works in a sandboxed frame that allows scripts under a policy that allows inline scripts, and its colors follow the viewer's light or dark scheme, unless the page's root theme draws in one mode by the stylesheets the page imports (a built theme's compiled stylesheet, or the page's own CSS), which the file keeps. A page whose script cannot be built for the browser (a module it loads needs Node, say) is refused. A page is refused with ERR_RENDER_COMPILE naming the file, the line, the module and the missing name, as a build refuses it, when it imports a name that one of its own modules, a StyleX variables module (`.stylex`) or an `@astryxdesign/*` package does not export, draws a member (`<Name.Member>`) such an export lacks, or imports any package subpath the package does not export (a named, default or side-effect import). A name another package does not export is refused only when the page's script is built: a page that draws or calls it as it renders fails with ERR_RENDER_FAILED first. Not checked: type imports, a name the page never uses as a value, a default import from a module that exists, a named import from one of the page's own CommonJS modules (a bundler reads those by interop), and a name the page imports through a TypeScript module that only re-exports it with a plain `export {…}` (such a page fails with ERR_RENDER_FAILED if it draws or calls the name as it renders). After writing, the render checks the file it wrote: what its markup and stylesheets load from outside the file, and whether `--reverse` gives back every carried file exactly. It reports a failed check by name, never blocks the write, and names the one file to share when the file stands alone. It says what the file's size is made of: the script, the CSS, the markup (with its inlined images) and the embedded source, each in bytes (`scriptBytes`, `cssBytes`, `markupBytes`, `sourceBytes`), and when the script is most of it. Warnings name anything that may differ from what the author meant, such as a component that did not render the text it was given. The file opens with a plain note for its next reader, a person or an agent: the CLI version and render format that made it, the page's path, the files it carries, the packages and versions it rendered with, and the exact commands that give the page back and render it again; the embedded source records the same facts and the markup as rendered. Each file the page uses that a render cannot carry is named on the note's 'Not carried' line and in `notCarried` (the JSON result and the text output), and its warning says why; the note then no longer says the page comes back exactly. A file left out because its name reads as a tool's configuration gets the `not-carried` warning, which says what carries it. With `reverse` (the way back, or unrender), it writes the embedded source back byte for byte, and only the files a render embeds: the page and the local modules, stylesheets, JSON files and images it imports, into a new folder; it also reports the render format, the CLI version and packages that rendered the file, and whether someone changed the markup after the render, naming each run of text that changed and where the old text sits in the restored source (the restored files stay the page as rendered); a file with Astryx markup but no embedded source is rebuilt from its component class names and data attributes (text and layout only); any other file is refused. Experimental: it may change or be removed in a patch release.",
importPath: '@astryxdesign/cli/api/experimental',
signature:
'render(file: string, options?: RenderOptions): Promise<RenderPageResponse | RenderReverseResponse>',
Expand Down
Loading