Make a shareable page
Experimental. Write a page with Astryx components, render it to one HTML file, share or upload that file, and turn it back into source to change it.Four steps
A shareable page is one HTML file. It opens in a browser, as an attachment, or in an artifact viewer that shows HTML in a sandboxed frame. It loads nothing from the network, and it carries the page’s own script, so its controls work as in the app. It also carries its own source, so anyone who has the file can turn it back into code, change it, and render it again. The render command is experimental: its options and its output can change in a patch release.
- Write the page: one
.tsxfile built from Astryx components. - Render it to one HTML file.
- Share or upload that file.
- To change it, turn the file back into source, edit the source, and render again.
1. Write the page
Make a folder and write one file, such as page.tsx. Its default export is a React component built from Astryx components. In a folder that is not an Astryx project, the CLI renders the page with its own Astryx, React and StyleX, so the folder needs no package.json and no install.
tsximport {VStack} from '@astryxdesign/core/VStack';import {HStack} from '@astryxdesign/core/HStack';import {StackItem} from '@astryxdesign/core/Stack';import {Card} from '@astryxdesign/core/Card';import {Heading} from '@astryxdesign/core/Heading';import {Text} from '@astryxdesign/core/Text';import {Badge} from '@astryxdesign/core/Badge';export default function Page() {return (<VStack gap={5} padding={6}><HStack gap={2} vAlign="center"><StackItem size="fill"><Heading level={1}>Project Atlas</Heading></StackItem><StackItem size="static"><Badge label="At risk" variant="warning" /></StackItem></HStack><Card padding={5}><Text type="body">38% of traffic is on the new stack.</Text></Card></VStack>);}
Find a component with npx @astryxdesign/cli search "progress bar" and read its props with npx @astryxdesign/cli component ProgressBar before you use it. Use components and tokens, not colors or CSS of your own: the page then follows the reader’s light or dark setting, and a viewer that sets Astryx theme variables gives it that viewer’s theme.
- Readers open the file on phones and on wide screens. Put cards in a row with
<Grid columns={{minWidth: 220, max: 3}}>, which drops to fewer columns on a narrow screen, down to one. Do not pick a layout with script, such asuseMediaQuery: every reader, on any screen, first sees the one layout that the query’s server answer (false) picks, and keeps it in a viewer that blocks scripts; elsewhere it changes once the script runs. - A row runs out of room first. In an
HStack, aBadgebeside a long heading or text shrinks and cuts off its label. Wrap the badge in<StackItem size="static">so it keeps its size, and the text in<StackItem size="fill">so the text wraps, as the example does.StackItemcomes from@astryxdesign/core/Stack. - A
VStackstretches each child to its full width, so aBadgeorTokenon a line of its own becomes a bar across the page. Wrap that one item in<StackItem crossAlignSelf="start">. Do not give theVStackhAlign="start": it shrinks every child, Cards and Grids too. - A
ListItemlabelordescriptionthat is a string stays on one line and ends in an ellipsis, and the file cannot show the rest. When readers need the whole text, pass an element:label={<Text type="body">…</Text>}. - The file cannot scroll a table sideways, because that needs script: a table wider than the screen is cut off at its edge. Inside the example’s
padding={6}, a 375 px phone leaves about 327 px, so keep a table that phones must show within about 310 px, and put the other columns in a second table or in Cards. A table is as wide as itspixel()columns plus, for itsproportional()columns, the largest floor divided by that column’s share of all the shares: fourproportional(1)columns at the default 120 px floor need 480 px. So make each share equal its floor, as inproportional(148, {minWidth: 148}), or give the columnspixel()widths; then the floors add up. A column with nowidthcounts asproportional(1, {minWidth: 60}), so give every column of a phone table a width. - A column’s floor includes its cells’ 24 px of padding. It must fit the column’s longest word, because wrapped text breaks inside a word that does not fit, and its header, which stays on one line and is cut off with an ellipsis:
width: pixel(64)holds a short number under a one-word header such as “p95”, and a two-word header such as “Error rate” needs about 100 px. - Give each
CodeBlockisWrapped, so a reader on a phone sees whole lines. - Charts use recharts: install it in the page’s folder first (
npm install recharts). Size a chart with<ResponsiveContainer width="100%" aspect={2.5}>, and color each series with a theme variable, such asstroke="var(--color-data-categorical-blue)", so it follows the theme too. - Controls that need a browser (buttons, filters, tabs, menus) work once the page’s script runs, and do nothing in a viewer that blocks scripts. Keep what a reader must see in the first paint, not behind a click (see
npx @astryxdesign/cli docs cli/experimental/render-pages interactive).
2. Render it to one file
bashnpx @astryxdesign/cli experimental render page.tsx --out page.html
Read what the command prints. A warning names something that can look different from what you meant, such as a component that ignores its children or a remote image the viewer cannot load, and says what to change; fix it and render again. When the command says a package is not installed, install that package in the page’s folder and render again. Then check the file: open it in a browser if you have one, or run the reverse command in step 4 to see that its source comes back.
The file is the whole page: send it, put it on a web host, or upload it to an artifact viewer that accepts one HTML file. A viewer that shows HTML in a frame with no network shows it as it is; one that also blocks scripts shows its first paint. Upload it with the host’s own command, and keep the link or ID it gives back: you update that same artifact later, so readers keep the same link.
The file carries the page’s source and every local file the page imports. Whoever has the file can read them, so keep secrets out of the page and its imports.
4. Change it later
Change the page through its source, never by editing the HTML: the source inside the file does not change with the markup, so the next person who turns it back gets the old page.
- Get the current file, such as the latest version of the artifact: the shared copy can be newer than yours.
- Turn it back into source.
npx @astryxdesign/cli experimental render --reverse page.htmlwrites the page and every local file it imports into a new folder beside the file:page-restored/, orpage-restored-2/when that folder exists. The command prints the folder it wrote. - Edit the page in that folder, such as
page-restored/page.tsx. - Render it over the old file:
npx @astryxdesign/cli experimental render page-restored/page.tsx --out page.html. The command replaces a file only when a render wrote it. - Share the new file, or upload it as a new version of the same artifact.
Run each command from the folder that holds the file: a relative --out stays inside the folder you run it from, and --reverse writes only there. An absolute --out can name any folder. When the restored page imports a package, such as recharts or an icon set, install it in that folder first; the render names each package that is missing.
When a step fails
ERR_RENDER_BROWSER_API: the page readswindowordocumentwhile it renders. Move that into an effect, or remove it.- The page looks wrong on a phone: a layout picked by script, a badge stretched across the page or cut off, a list label cut off, or a table cut off or with words broken in the middle. See step 1.
- The render refuses to write the output: it replaces only a file a render wrote. Choose another
--outname.
Every detail of the command, such as what it carries, its warnings, and files from other CLI versions: npx @astryxdesign/cli docs cli/experimental/render-pages.