Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

[fix] render: outside a project, take Astryx from the copy the CLI runs with (#10362)

Joey658c896ec2b0
diff --git a/.changeset/render-outside-project.md b/.changeset/render-outside-project.md
new file mode 100644
index 0000000000..8b6409d9a0
--- /dev/null
+++ b/.changeset/render-outside-project.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx experimental render`: a page outside a project now renders. Outside a project (no Core or CLI the folder reads, and no package.json that declares one), the page takes the `@astryxdesign/*` packages its folder lacks, and the integrations a host approves, from the copy the CLI itself runs with, instead of failing with ERR_RENDER_MISSING_DEPENDENCY. React and StyleX come from that copy too, so the page loads one copy of each, even in a React app that installs its own. When that copy's Core cannot be downloaded, a page that needs it fails with ERR_VERSIONS_UNAVAILABLE, as other commands that read Core do. Inside a project, the page uses only the project's own packages.
+
+@josephfarina
diff --git a/packages/cli/api/render/_adapter.mjs b/packages/cli/api/render/_adapter.mjs
index 75b706e098..a2e75b28b7 100644
--- a/packages/cli/api/render/_adapter.mjs
+++ b/packages/cli/api/render/_adapter.mjs
@@ -26,6 +26,10 @@ import {isAstryxMarkup} from '../../foundation/render/html-reader.mjs';
import {rebuildPage} from '../../foundation/render/rebuild.mjs';
import {cliVersion} from '../../foundation/integrations/cli-peer-version.mjs';
import {assertWithin, PathSafetyError} from '../../foundation/fs/path-safety.mjs';
+import {requireCoreDir} from '../../foundation/fs/paths.mjs';
+import {runChoice} from '../../foundation/release/run-context.mjs';
+import {isServedPackage} from '../../foundation/render/served-packages.mjs';
+import {hostedRun, recordResolved} from '../../foundation/runtime/package-root.mjs';
export {PAGE_EXTENSIONS, embeddedPathProblem};
@@ -238,6 +242,29 @@ function asAstryxError(e) {
return e;
}
+/**
+ * The package set the CLI runs from, for a page outside a project
+ * (architecture:cli-surface INV30): the Core it carries, found by the rule of
+ * every command that answers from Core outside a project. Inside a project
+ * (spec AST-081: a Core or CLI the folder reads, or a package.json that
+ * declares one) the project's packages serve the page alone, so this is
+ * null.
+ * When the carried Core cannot be had, the reason is kept for the error a
+ * page that needs it gets (spec AST-081 FR3).
+ * @param {string} input absolute path of the page
+ * @returns {{dir: string, integrations: readonly string[]} | {unavailable: Error} | null}
+ */
+function servedSet(input) {
+ const dir = path.dirname(input);
+ if (runChoice(dir).inProject) return null;
+ try {
+ return {dir: requireCoreDir(dir), integrations: hostedRun()?.integrations ?? []};
+ } catch (e) {
+ const err = /** @type {any} */ (e);
+ return err?.code === ERROR_CODES.ERR_VERSIONS_UNAVAILABLE ? {unavailable: err} : null;
+ }
+}
+
/**
* Render a page module to one HTML file and write it.
* @param {{cwd: string, input: string, output: string, title?: string}} args absolute paths
@@ -249,10 +276,29 @@ export async function renderToFile({cwd, input, output, title}) {
/** @type {import('../../foundation/render/render-page.mjs').RenderedPage} */
let page;
try {
- page = await renderPage(input, {title, version: cliVersion()});
+ const set = servedSet(input);
+ try {
+ page = await renderPage(input, {title, version: cliVersion(), served: set && 'dir' in set ? set : null});
+ } catch (e) {
+ // A page that needs the Core the CLI could not obtain says why.
+ const missing = /** @type {any} */ (e)?.code === 'ERR_RENDER_MISSING_DEPENDENCY' ? /** @type {any} */ (e).detail?.package : null;
+ if (set && 'unavailable' in set && typeof missing === 'string' && isServedPackage(missing, hostedRun()?.integrations ?? [])) {
+ throw new AstryxError(set.unavailable.message, [], ERROR_CODES.ERR_VERSIONS_UNAVAILABLE);
+ }
+ throw e;
+ }
} catch (e) {
throw asAstryxError(e);
}
+ for (const {name, dir} of page.fromSet) {
+ let version = null;
+ try {
+ version = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version;
+ } catch {
+ // A package without a readable version is still named.
+ }
+ recordResolved(name, version, dir, 'package-set');
+ }
refuseProtected([output], cwd);
// An existing file is replaced only when a render wrote it.
if (
diff --git a/packages/cli/api/render/render.doc.mjs b/packages/cli/api/render/render.doc.mjs
index 00c4298390..84f4752b23 100644
--- a/packages/cli/api/render/render.doc.mjs
+++ b/packages/cli/api/render/render.doc.mjs
@@ -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, and writes ONE static HTML file that needs nothing beside it: the page's own StyleX styles are compiled, Core's stylesheets are cut to the rules the markup uses (layer order, custom properties and keyframes kept), local images become data: URIs, and the page's source is embedded so it can be given back exactly. The file runs no script and loads nothing from the network, so it works inside a sandboxed frame with a strict content security policy, and its colors follow the viewer's light or dark scheme. Warnings name anything that may differ from what the author meant, such as a component that did not render the text it was given. With `reverse`, 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; 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 writes ONE static HTML file that needs nothing beside it: the page's own StyleX styles are compiled, Core's stylesheets are cut to the rules the markup uses (layer order, custom properties and keyframes kept), local images become data: URIs, and the page's source is embedded so it can be given back exactly. The file runs no script and loads nothing from the network, so it works inside a sandboxed frame with a strict content security policy, and its colors follow the viewer's light or dark scheme. Warnings name anything that may differ from what the author meant, such as a component that did not render the text it was given. With `reverse`, 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; 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>',
@@ -92,6 +92,7 @@ export const doc = {
{code: 'ERR_RENDER_COMPILE', when: 'the page does not compile, or a stylesheet it imports is not valid CSS (the message names the file)'},
{code: 'ERR_RENDER_NO_DEFAULT_EXPORT', when: 'the page has no default export'},
{code: 'ERR_RENDER_MISSING_DEPENDENCY', when: 'the page imports a package that is not installed; the suggestion is its install line'},
+ {code: 'ERR_VERSIONS_UNAVAILABLE', when: 'outside a project, the page imports an Astryx package, React or StyleX, and the Core of the release that answers cannot be downloaded'},
{code: 'ERR_RENDER_BROWSER_API', when: 'the page reads a browser-only API, such as window or document, while rendering'},
{code: 'ERR_RENDER_ASSET_TOO_LARGE', when: 'a local file the page uses is over 8 MB'},
{code: 'ERR_RENDER_TIMEOUT', when: 'the page does not finish rendering within 60 seconds'},
diff --git a/packages/cli/api/render/render.test.mjs b/packages/cli/api/render/render.test.mjs
index f87de5b584..ea8887d29a 100644
--- a/packages/cli/api/render/render.test.mjs
+++ b/packages/cli/api/render/render.test.mjs
@@ -5,7 +5,9 @@
* self-contained HTML file and back, each refusal, and the warnings.
*/
+import {spawnSync} from 'node:child_process';
import * as fs from 'node:fs';
+import {createRequire} from 'node:module';
import * as os from 'node:os';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
@@ -1155,3 +1157,127 @@ describe('render(): refusals', () => {
expect(await codeOf(() => render('big.tsx', {cwd: dir}))).toBe('ERR_RENDER_ASSET_TOO_LARGE');
}, 30_000);
});
+
+describe('render(): a page outside a project', () => {
+ /** @type {string} */
+ let away;
+ const BIN = path.join(CLI_DIR, 'clients', 'cli', 'bin', 'astryx.mjs');
+
+ /** @param {string} cwd @param {string[]} args */
+ const runBin = (cwd, args) => {
+ // A test runner's NODE_PATH would reach this repository's packages.
+ const {NODE_PATH: _, ...env} = process.env;
+ const run = spawnSync(process.execPath, [BIN, '--json', ...args], {cwd, env, encoding: 'utf8', timeout: 60_000});
+ return {status: run.status, json: JSON.parse(run.stdout)};
+ };
+
+ beforeAll(() => {
+ away = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-render-away-')));
+ });
+
+ afterAll(() => {
+ fs.rmSync(away, {recursive: true, force: true});
+ });
+
+ it('takes Astryx, React and StyleX from the copy the CLI runs with', () => {
+ fs.writeFileSync(path.join(away, 'page.tsx'), PAGE);
+ fs.writeFileSync(path.join(away, 'dot.png'), PNG);
+ const run = runBin(away, ['experimental', 'render', 'page.tsx']);
+ expect(run.status).toBe(0);
+ expect(run.json.data.stylesheets).toContain('@astryxdesign/core/astryx.css');
+ expect(run.json.data.warnings.map((/** @type {any} */ w) => w.code)).not.toContain('no-astryx-styles');
+ const html = fs.readFileSync(path.join(away, 'page.html'), 'utf8');
+ expect(html).toContain('Café ✓ report');
+ expect(html).toContain('astryx-button');
+ const back = runBin(away, ['experimental', 'render', '--reverse', 'page.html']);
+ expect(back.json.data.exact).toBe(true);
+ expect(fs.readFileSync(path.join(away, 'page-restored', 'page.tsx'), 'utf8')).toBe(PAGE);
+ }, 60_000);
+
+ it('loads one React outside a project, even when the folder holds its own copy', () => {
+ const sub = path.join(away, 'own-react');
+ for (const name of ['react', 'react-dom']) {
+ const target = path.dirname(createRequire(path.join(CLI_DIR, '../core/package.json')).resolve(`${name}/package.json`));
+ fs.mkdirSync(path.join(sub, 'node_modules'), {recursive: true});
+ fs.cpSync(target, path.join(sub, 'node_modules', name), {recursive: true, dereference: true});
+ }
+ fs.writeFileSync(
+ path.join(sub, 'page.jsx'),
+ "import {useState} from 'react';\nimport {TextInput} from '@astryxdesign/core';\nexport default function Page() {\n const [v] = useState('typed');\n return <TextInput label=\"Name\" value={v} onChange={() => {}} />;\n}\n",
+ );
+ const run = runBin(sub, ['experimental', 'render', 'page.jsx']);
+ expect(run.status).toBe(0);
+ expect(fs.readFileSync(path.join(sub, 'page.html'), 'utf8')).toContain('typed');
+ }, 60_000);
+
+ it('gives a library in the folder the same React, as CommonJS and as an ES module', () => {
+ const sub = path.join(away, 'react-app');
+ const nm = path.join(sub, 'node_modules');
+ for (const name of ['react', 'react-dom']) {
+ const target = path.dirname(createRequire(path.join(CLI_DIR, '../core/package.json')).resolve(`${name}/package.json`));
+ fs.mkdirSync(nm, {recursive: true});
+ fs.cpSync(target, path.join(nm, name), {recursive: true, dereference: true});
+ }
+ fs.mkdirSync(path.join(nm, 'hook-cjs'), {recursive: true});
+ fs.writeFileSync(path.join(nm, 'hook-cjs', 'package.json'), '{"name":"hook-cjs","main":"index.js"}');
+ fs.writeFileSync(path.join(nm, 'hook-cjs', 'index.js'), "const {useState} = require('react');\nexports.useCjs = () => useState('cjs-hook')[0];\n");
+ fs.mkdirSync(path.join(nm, 'hook-esm'), {recursive: true});
+ fs.writeFileSync(path.join(nm, 'hook-esm', 'package.json'), '{"name":"hook-esm","type":"module","exports":"./index.js"}');
+ fs.writeFileSync(path.join(nm, 'hook-esm', 'index.js'), "import {useState} from 'react';\nexport const useEsm = () => useState('esm-hook')[0];\n");
+ const body = " const a = useCjs();\n const b = useEsm();\n";
+ fs.writeFileSync(
+ path.join(sub, 'plain.jsx'),
+ `import {useCjs} from 'hook-cjs';\nimport {useEsm} from 'hook-esm';\nexport default function Page() {\n${body} return <p>{a} {b}</p>;\n}\n`,
+ );
+ fs.writeFileSync(
+ path.join(sub, 'core.jsx'),
+ `import {useCjs} from 'hook-cjs';\nimport {useEsm} from 'hook-esm';\nimport {Button} from '@astryxdesign/core';\nexport default function Page() {\n${body} return <Button label={a + ' ' + b} />;\n}\n`,
+ );
+ for (const page of ['plain', 'core']) {
+ const run = runBin(sub, ['experimental', 'render', `${page}.jsx`]);
+ expect(run.status).toBe(0);
+ const html = fs.readFileSync(path.join(sub, `${page}.html`), 'utf8');
+ expect(html).toContain('cjs-hook');
+ expect(html).toContain('esm-hook');
+ }
+ }, 90_000);
+
+ it('says the CLI runs without Core only for a render outside a project', async () => {
+ const sub = path.join(away, 'no-core');
+ for (const name of ['react', 'react-dom']) {
+ const target = path.dirname(createRequire(path.join(CLI_DIR, '../core/package.json')).resolve(`${name}/package.json`));
+ fs.mkdirSync(path.join(sub, 'node_modules'), {recursive: true});
+ fs.cpSync(target, path.join(sub, 'node_modules', name), {recursive: true, dereference: true});
+ }
+ fs.writeFileSync(path.join(sub, 'page.jsx'), 'export default () => <p>no core</p>;\n');
+ // In a fresh process without the test runner's NODE_PATH, which would reach this repository's Core.
+ const script = `
+const {renderPage} = await import(${JSON.stringify(path.join(CLI_DIR, 'foundation/render/render-page.mjs'))});
+const entry = ${JSON.stringify(path.join(sub, 'page.jsx'))};
+const textOf = page => page.warnings.find(w => w.code === 'no-astryx-styles')?.message;
+const inside = textOf(await renderPage(entry, {served: null}));
+const outside = textOf(await renderPage(entry, {served: {dir: ${JSON.stringify(path.join(sub, 'no-such-core'))}, integrations: []}}));
+console.log(JSON.stringify({inside, outside}));
+`;
+ const {NODE_PATH: _, ...env} = process.env;
+ const run = spawnSync(process.execPath, ['--input-type=module', '-e', script], {cwd: sub, env, encoding: 'utf8', timeout: 60_000});
+ const {inside, outside} = JSON.parse(run.stdout.trim().split('\n').pop() ?? '{}');
+ expect(inside).toBe('@astryxdesign/core is not installed where the page is, so the page has no Astryx styles; install it, or render from inside the project.');
+ expect(outside).toContain('and the CLI runs without one');
+ }, 60_000);
+
+ it('still names a package the CLI does not carry as not installed', () => {
+ fs.writeFileSync(path.join(away, 'dep.jsx'), "import x from 'not-a-real-package-xyz';\nexport default () => <p>{String(x)}</p>;\n");
+ const run = runBin(away, ['experimental', 'render', 'dep.jsx']);
+ expect(run.json.code).toBe('ERR_RENDER_MISSING_DEPENDENCY');
+ }, 60_000);
+
+ it("uses only the project's own packages inside a project", async () => {
+ const {renderPage} = await import('../../foundation/render/render-page.mjs');
+ const page = await renderPage(path.join(dir, 'page.tsx'), {
+ served: {dir: path.join(away, 'no-such-core'), integrations: []},
+ });
+ expect(page.fromSet).toEqual([]);
+ expect(page.stylesheets).toContain('@astryxdesign/core/astryx.css');
+ }, 60_000);
+});
diff --git a/packages/cli/assets/docs/tree/render-pages.doc.mjs b/packages/cli/assets/docs/tree/render-pages.doc.mjs
index d40c0621fe..808019a5c9 100644
--- a/packages/cli/assets/docs/tree/render-pages.doc.mjs
+++ b/packages/cli/assets/docs/tree/render-pages.doc.mjs
@@ -44,7 +44,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'Build the page with Astryx components as usual, then render it. The page module needs a default export; it renders on your machine with the React and Astryx packages your project installed.',
+ text: 'Build the page with Astryx components as usual, then render it. The page module needs a default export; it renders on your machine with the React and Astryx packages your project installed. Outside a project (no Astryx Core or CLI installed or declared for the folder), it renders with the Astryx, React and StyleX that the CLI itself runs with, so a single page file renders anywhere, a React app included.',
},
{
type: 'code',
diff --git a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs b/packages/cli/foundation/doc-compiler/doc-loads.test.mjs
index d7a8103a4b..c276565149 100644
--- a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs
+++ b/packages/cli/foundation/doc-compiler/doc-loads.test.mjs
@@ -355,8 +355,14 @@ const RUNNERS = {
sites: ['importDocModule', 'importNativeModule ×3', 'importTemplateModule'],
},
'foundation/render/page-worker.mjs': {
- runs: 'the page `astryx experimental render` renders, its local modules, React, and the StyleX compiler, in a worker',
- sites: ['.import() ×3', 'createJiti ×2', 'require(@stylexjs/babel-plugin)'],
+ runs: 'the page `astryx experimental render` renders, its local modules, React, and the StyleX compiler, in a worker; outside a project, Node resolves the packages its folder lacks, and React and StyleX for every module (resolve hooks for ES modules), from the package set the CLI runs from',
+ sites: [
+ '.import() ×3',
+ 'createJiti ×2',
+ 'module',
+ 'module.register',
+ 'require(@stylexjs/babel-plugin)',
+ ],
},
'foundation/render/render-page.mjs': {
runs: 'the render worker, so a page that never finishes can be stopped',
diff --git a/packages/cli/foundation/render/page-worker.mjs b/packages/cli/foundation/render/page-worker.mjs
index bd02b4511f..070495122c 100644
--- a/packages/cli/foundation/render/page-worker.mjs
+++ b/packages/cli/foundation/render/page-worker.mjs
@@ -8,7 +8,11 @@
* It runs in a worker thread so a page that never finishes rendering can be
* stopped, and so nothing the page prints reaches the CLI's own output.
*
- * @input workerData {entry, root}
+ * Outside a project, the Astryx packages the page's folder lacks resolve
+ * from the package set the CLI runs from (served-packages.mjs), and React and
+ * StyleX always come from that set, so the page loads one copy of each.
+ *
+ * @input workerData {entry, root, served}
* @output one message: {ok: true, markup, css, files, texts, logs} or
* {ok: false, error: {code, message, detail?}}
* @position foundation/render — started by render-page.mjs
@@ -16,17 +20,23 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
-import {createRequire} from 'node:module';
+import Module, {createRequire, register} from 'node:module';
+import {pathToFileURL} from 'node:url';
import {format} from 'node:util';
import {parentPort, workerData} from 'node:worker_threads';
import {transformSync} from '@babel/core';
import {createJiti} from 'jiti';
import {assetDataUri, isAssetPath} from './assets.mjs';
+import {SINGLE_COPY, isServedPackage, packageOf} from './served-packages.mjs';
+import {findNodeModulesPackage} from '../fs/paths.mjs';
/** @typedef {{level: string, text: string}} PageLog */
-/** @type {{entry: string, root: string}} */
+/** @type {{entry: string, root: string, served: {dir: string, integrations: string[]} | null}} */
const {entry, root} = workerData;
+
+/** The package set, for a page outside a project whose folder has no Core of its own. */
+const served = workerData.served && findNodeModulesPackage(path.dirname(entry), '@astryxdesign/core') === null ? workerData.served : null;
const ROOT_PREFIX = root.endsWith(path.sep) ? root : root + path.sep;
/** @type {PageLog[]} */
@@ -348,6 +358,96 @@ const resolveAlias = spec => {
return spec;
};
+/** Packages the page took from the package set, by name: their folders. */
+/** @type {Map<string, string>} */
+const fromSet = new Map();
+
+/**
+ * The folder of the package that holds `file`.
+ * @param {string} file
+ * @param {string} name
+ * @returns {string}
+ */
+function packageDirOf(file, name) {
+ for (let d = path.dirname(file); path.dirname(d) !== d; d = path.dirname(d)) {
+ try {
+ if (JSON.parse(fs.readFileSync(path.join(d, 'package.json'), 'utf8')).name === name) return d;
+ } catch {
+ // No package.json here, or one that does not parse: look further up.
+ }
+ }
+ return path.dirname(file);
+}
+
+const moduleApi = /** @type {any} */ (Module);
+
+/** A module at the served Core's folder: what resolves as the Core would. */
+const servedParent = served ? new moduleApi(path.join(served.dir, 'package.json')) : null;
+if (servedParent && served) {
+ servedParent.filename = servedParent.id;
+ servedParent.paths = moduleApi._nodeModulePaths(served.dir);
+}
+
+/**
+ * When the page's folder has no copy of a served package, take the one the
+ * package set holds. Node's resolver keeps each package's `exports`.
+ */
+function serveFromSet() {
+ if (!served || !servedParent) return;
+ const resolveFilename = moduleApi._resolveFilename;
+ moduleApi._resolveFilename = function (/** @type {string} */ request, /** @type {any[]} */ ...rest) {
+ // React, React DOM and StyleX come from the set for every module, a
+ // library in the page's folder included, so the page runs on one copy.
+ if (!request.startsWith('.') && !path.isAbsolute(request) && packageOf(request) in SINGLE_COPY_ALIASES) {
+ try {
+ return resolveFilename.call(this, request, servedParent, false);
+ } catch {
+ // The set has no such file: the importer's own copy serves.
+ }
+ }
+ try {
+ return resolveFilename.call(this, request, ...rest);
+ } catch (e) {
+ const name = /** @type {any} */ (e)?.code === 'MODULE_NOT_FOUND' && !request.startsWith('.') && !path.isAbsolute(request)
+ ? packageOf(request)
+ : null;
+ if (!name || !isServedPackage(name, served.integrations)) throw e;
+ const file = resolveFilename.call(this, request, servedParent, false);
+ if (!fromSet.has(name)) fromSet.set(name, packageDirOf(file, name));
+ return file;
+ }
+ };
+}
+
+/**
+ * React and StyleX keep state per copy, and the packages from the set load
+ * the set's copy. So outside a project the page's own modules load that copy
+ * too, even when its folder holds another one.
+ * @returns {Record<string, string>}
+ */
+function singleCopyAliases() {
+ /** @type {Record<string, string>} */
+ const alias = {};
+ if (!servedParent) return alias;
+ for (const name of SINGLE_COPY) {
+ try {
+ alias[name] = path.dirname(moduleApi._resolveFilename(`${name}/package.json`, servedParent, false));
+ } catch {
+ // The set has no copy: the page's own copy, if any, serves.
+ }
+ }
+ return alias;
+}
+const SINGLE_COPY_ALIASES = singleCopyAliases();
+serveFromSet();
+// ES modules follow the same rule through resolve hooks (CommonJS goes
+// through serveFromSet).
+if (servedParent && Object.keys(SINGLE_COPY_ALIASES).length > 0) {
+ register(new URL('./single-copy-hooks.mjs', import.meta.url), {
+ data: {parent: pathToFileURL(servedParent.filename).href, names: Object.keys(SINGLE_COPY_ALIASES)},
+ });
+}
+
const plain = createJiti(entry, {fsCache: false, jsx: {runtime: 'automatic'}});
const jiti = createJiti(entry, {
@@ -356,7 +456,7 @@ const jiti = createJiti(entry, {
extensions: ['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.mts', '.cts', '.json'],
moduleCache: true,
interopDefault: true,
- alias: ALIASES,
+ alias: {...SINGLE_COPY_ALIASES, ...ALIASES},
jsx: {runtime: 'automatic'},
transform(opts) {
const filename = opts.filename ?? '';
@@ -495,6 +595,10 @@ try {
classify(e);
throw null;
}
+ // The render always runs on React; StyleX only when the page uses it.
+ for (const [name, dir] of Object.entries(SINGLE_COPY_ALIASES)) {
+ if (name !== '@stylexjs/stylex' || packages.has(name)) fromSet.set(name, dir);
+ }
/** @type {string} */
let css = '';
if (stylexRules.length > 0) {
@@ -508,6 +612,7 @@ try {
packages: [...packages],
packageCss,
skippedCss,
+ fromSet: [...fromSet].map(([name, dir]) => ({name, dir})),
assets: [...assetsInlined],
files: localFiles,
texts,
diff --git a/packages/cli/foundation/render/render-page.mjs b/packages/cli/foundation/render/render-page.mjs
index 17e8808148..bc2f82fd6d 100644
--- a/packages/cli/foundation/render/render-page.mjs
+++ b/packages/cli/foundation/render/render-page.mjs
@@ -18,13 +18,13 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
-import {createRequire} from 'node:module';
import {Worker} from 'node:worker_threads';
import postcss from 'postcss';
import {assetDataUri, isAssetBytes, isAssetPath, RenderAssetError} from './assets.mjs';
import {classesIn, cutCss, layerOrderOf} from './css-cut.mjs';
import {sourceBlock} from './source-block.mjs';
import {embeddedPathProblem} from './embedded-files.mjs';
+import {resolveServed} from './served-packages.mjs';
/** How long one page may take to render before it is stopped. */
export const RENDER_TIMEOUT_MS = 60_000;
@@ -47,6 +47,7 @@ export {PAGE_EXTENSIONS} from './embedded-files.mjs';
* @property {number} markupBytes - Bytes of rendered markup.
* @property {number} images - Local files inlined as data: URIs.
* @property {RenderWarning[]} warnings
+ * @property {{name: string, dir: string}[]} fromSet - Packages that came from the package set the CLI runs from, not the page's folder.
*/
/** An error carrying a render error code. */
@@ -128,7 +129,7 @@ function importParams(params) {
* cut.
* @param {string} file the stylesheet's own path
* @param {string} css its text
- * @param {{warnings: RenderWarning[], carried: Set<string>, included: Set<string>, packageSheets: string[], seen?: Set<string>}} ctx
+ * @param {{warnings: RenderWarning[], carried: Set<string>, included: Set<string>, packageSheets: string[], served: ServedSet | null, seen?: Set<string>}} ctx
* `included`: stylesheet files already in the page (Core's, say), never
* inlined twice; `packageSheets`: package stylesheets this pulled in
* @returns {string}
@@ -170,12 +171,8 @@ function expandImports(file, css, ctx) {
if (/^\.{1,2}\//.test(url) || fs.existsSync(relative)) {
target = fs.existsSync(relative) ? relative : null;
} else {
- try {
- target = createRequire(file).resolve(url.replace(/^~/, ''));
- fromPackage = true;
- } catch {
- target = null;
- }
+ target = resolveServed(url.replace(/^~/, ''), file, ctx.served);
+ fromPackage = target !== null;
}
if (!target) {
ctx.warnings.push({
@@ -221,17 +218,20 @@ function expandImports(file, css, ctx) {
return root.toString();
}
+/** @typedef {{dir: string, integrations: readonly string[]}} ServedSet */
+
/**
* Run the page in a worker, stopping it after `timeoutMs`.
* @param {string} entry
* @param {string} root
* @param {number} timeoutMs
+ * @param {ServedSet | null} served
* @returns {Promise<any>}
*/
-function runWorker(entry, root, timeoutMs) {
+function runWorker(entry, root, timeoutMs, served) {
return new Promise((resolve, reject) => {
const worker = new Worker(new URL('./page-worker.mjs', import.meta.url), {
- workerData: {entry, root},
+ workerData: {entry, root, served: served ? {dir: served.dir, integrations: [...served.integrations]} : null},
execArgv: [],
stdout: true,
stderr: true,
@@ -361,13 +361,16 @@ const SCHEME_CSS =
/**
* Render a page module to one self-contained HTML file.
* @param {string} entry absolute path of the page module
- * @param {{title?: string, timeoutMs?: number, version?: string}} [options]
+ * @param {{title?: string, timeoutMs?: number, version?: string, served?: ServedSet | null}} [options]
+ * `served`: the Core of the package set the CLI runs from, for the packages
+ * the page's folder has no copy of
* @returns {Promise<RenderedPage>}
*/
export async function renderPage(entry, options = {}) {
const dir = path.dirname(entry);
const root = projectRootOf(dir);
- const message = await runWorker(entry, root, options.timeoutMs ?? RENDER_TIMEOUT_MS);
+ const served = options.served ?? null;
+ const message = await runWorker(entry, root, options.timeoutMs ?? RENDER_TIMEOUT_MS, served);
/** @type {RenderWarning[]} */
const warnings = [];
if (!message.ok) {
@@ -378,7 +381,6 @@ export async function renderPage(entry, options = {}) {
// Stylesheets: Core's reset and components, plus each official package's
// own stylesheet the page imports from.
- const req = createRequire(entry);
/** @type {string[]} */
const sheets = [];
/** @type {string[]} */
@@ -388,7 +390,8 @@ export async function renderPage(entry, options = {}) {
/** @param {string} spec */
const addSheet = spec => {
try {
- const file = req.resolve(spec);
+ const file = resolveServed(spec, entry, served);
+ if (!file) return false;
sheets.push(spec);
sheetText.push(fs.readFileSync(file, 'utf8'));
sheetFiles.push(file);
@@ -402,8 +405,9 @@ export async function renderPage(entry, options = {}) {
// Package stylesheets the page imports itself, such as a theme's.
for (const {spec, from} of /** @type {{spec: string, from: string}[]} */ (message.packageCss ?? [])) {
if (sheets.includes(spec)) continue;
+ const file = resolveServed(spec, from, served);
try {
- const file = createRequire(from).resolve(spec);
+ if (!file) throw new Error('not found');
sheets.push(spec);
sheetText.push(fs.readFileSync(file, 'utf8'));
sheetFiles.push(file);
@@ -422,8 +426,10 @@ export async function renderPage(entry, options = {}) {
if (!hasCore) {
warnings.push({
code: 'no-astryx-styles',
- message:
- '@astryxdesign/core is not installed where the page is, so the page has no Astryx styles; install it, or render from inside the project.',
+ // Outside a project the page would have taken the CLI's own Core.
+ message: served
+ ? '@astryxdesign/core is not installed where the page is, and the CLI runs without one, so the page has no Astryx styles; install it, or render from inside the project.'
+ : '@astryxdesign/core is not installed where the page is, so the page has no Astryx styles; install it, or render from inside the project.',
});
}
@@ -468,7 +474,7 @@ export async function renderPage(entry, options = {}) {
/** A stylesheet's rules cut to the page, with its own imports inlined. @param {string} file @param {string} text */
const sheet = (file, text) => {
try {
- const own = expandImports(file, text, {warnings, carried: carriedCss, included, packageSheets});
+ const own = expandImports(file, text, {warnings, carried: carriedCss, included, packageSheets, served});
return inlineAssets(cutCss(own, used), 'css', {...ctx, dir: path.dirname(file)});
} catch (e) {
if (e instanceof RenderAssetError || e instanceof RenderError) throw e;
@@ -608,5 +614,6 @@ export async function renderPage(entry, options = {}) {
...(message.assets ?? []),
]).size,
warnings,
+ fromSet: message.fromSet ?? [],
};
}
diff --git a/packages/cli/foundation/render/served-packages.mjs b/packages/cli/foundation/render/served-packages.mjs
new file mode 100644
index 0000000000..17df4c7240
--- /dev/null
+++ b/packages/cli/foundation/render/served-packages.mjs
@@ -0,0 +1,75 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Which packages a render may take from the package set the CLI runs
+ * from when the page is outside a project (architecture:cli-surface INV30):
+ * the Astryx packages, the React and StyleX they run with, and the
+ * integrations the host approves. Inside a project the set is never used.
+ *
+ * @input A specifier, the file that imports it, and the served Core's folder.
+ * @output The file it resolves to, or null.
+ * @position foundation/render — read by render-page.mjs and page-worker.mjs.
+ */
+
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+
+/** Packages every Astryx package runs with, besides its own scope. */
+const RUNTIME = ['react', 'react-dom', '@stylexjs/stylex'];
+
+/**
+ * React and StyleX hold state per copy, so a page outside a project loads
+ * the set's copy of each, as the packages from the set do.
+ */
+export const SINGLE_COPY = RUNTIME;
+
+/**
+ * The package a bare specifier names.
+ * @param {string} spec
+ * @returns {string}
+ */
+export function packageOf(spec) {
+ return spec.startsWith('@')
+ ? spec.split('/').slice(0, 2).join('/')
+ : spec.split('/')[0];
+}
+
+/**
+ * Whether a render may take `name` from the package set.
+ * @param {string} name
+ * @param {readonly string[]} integrations the integrations the host approves
+ * @returns {boolean}
+ */
+export function isServedPackage(name, integrations) {
+ return (
+ name.startsWith('@astryxdesign/') ||
+ RUNTIME.includes(name) ||
+ integrations.includes(name)
+ );
+}
+
+/**
+ * Resolve `spec` the way `from` sees it; when that fails and the package is
+ * one the set serves, the way the served Core's folder sees it.
+ * @param {string} spec
+ * @param {string} from the importing file
+ * @param {{dir: string, integrations: readonly string[]} | null} served
+ * @returns {string | null}
+ */
+export function resolveServed(spec, from, served) {
+ try {
+ return createRequire(from).resolve(spec);
+ } catch {
+ if (!served || !isServedPackage(packageOf(spec), served.integrations)) {
+ return null;
+ }
+ try {
+ return createRequire(path.join(served.dir, 'package.json')).resolve(
+ spec,
+ {paths: [served.dir]},
+ );
+ } catch {
+ return null;
+ }
+ }
+}
diff --git a/packages/cli/foundation/render/single-copy-hooks.mjs b/packages/cli/foundation/render/single-copy-hooks.mjs
new file mode 100644
index 0000000000..0ae46614d5
--- /dev/null
+++ b/packages/cli/foundation/render/single-copy-hooks.mjs
@@ -0,0 +1,44 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Module resolve hooks for a render outside a project: every ES module
+ * the page loads, a library in the page's folder included, takes React,
+ * React DOM and StyleX from the package set the CLI runs from, so the page
+ * runs on one copy of each. CommonJS goes through the same rule in
+ * page-worker.mjs.
+ *
+ * @input `initialize` data: `parent`, the URL to resolve from (the served
+ * Core's package.json), and `names`, the packages to take from there.
+ * @output A `resolve` hook.
+ * @position foundation/render — registered by page-worker.mjs.
+ */
+
+/** @type {string} */
+let parent = '';
+/** @type {string[]} */
+let names = [];
+
+/**
+ * @param {{parent: string, names: string[]}} data
+ */
+export function initialize(data) {
+ parent = data.parent;
+ names = data.names;
+}
+
+/**
+ * @param {string} specifier
+ * @param {{parentURL?: string}} context
+ * @param {(specifier: string, context?: object) => Promise<unknown>} nextResolve
+ */
+export async function resolve(specifier, context, nextResolve) {
+ const named = names.some(name => specifier === name || specifier.startsWith(`${name}/`));
+ if (named) {
+ try {
+ return await nextResolve(specifier, {...context, parentURL: parent});
+ } catch {
+ // The set has no such file: the importer's own copy serves.
+ }
+ }
+ return nextResolve(specifier, context);
+}
diff --git a/packages/cli/foundation/runtime/hosted-runtime.test.mjs b/packages/cli/foundation/runtime/hosted-runtime.test.mjs
index 3a982c2fe5..21b1a7f549 100644
--- a/packages/cli/foundation/runtime/hosted-runtime.test.mjs
+++ b/packages/cli/foundation/runtime/hosted-runtime.test.mjs
@@ -14,6 +14,7 @@
import {describe, it, expect, afterEach} from 'vitest';
import {spawnSync} from 'node:child_process';
import * as fs from 'node:fs';
+import {createRequire} from 'node:module';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {
@@ -76,7 +77,8 @@ process.exitCode = result.status;
env: {
...Object.fromEntries(
Object.entries(process.env).filter(
- ([key]) => !/^(?:npm_|CI$|NO_UPDATE_NOTIFIER$)/iu.test(key),
+ ([key]) =>
+ !/^(?:npm_|CI$|NO_UPDATE_NOTIFIER$|NODE_PATH$)/iu.test(key),
),
),
HOME: home,
@@ -378,6 +380,117 @@ describe('what a hosted run resolved', () => {
);
});
+ it('renders a page in an empty folder from the package set: Core, React and StyleX', () => {
+ const cwd = tempDir('empty');
+ fs.writeFileSync(
+ path.join(cwd, 'page.jsx'),
+ `import * as stylex from '@stylexjs/stylex';
+import {Button} from '@astryxdesign/core';
+const styles = stylex.create({box: {padding: 12}});
+export default function Page() {
+ return <div {...stylex.props(styles.box)}><Button label="Hosted" /></div>;
+}
+`,
+ );
+ const run = host({
+ argv: ['--json', 'experimental', 'render', 'page.jsx'],
+ cwd,
+ });
+ expect(run.status).toBe(0);
+ expect(JSON.parse(run.stdout).type).toBe('render.page');
+ expect(fs.readFileSync(path.join(cwd, 'page.html'), 'utf-8')).toContain(
+ 'Hosted',
+ );
+ const sources = Object.fromEntries(
+ run
+ .result()
+ .packages.map((/** @type {{name: string, source: string}} */ p) => [
+ p.name,
+ p.source,
+ ]),
+ );
+ for (const name of [
+ '@astryxdesign/core',
+ 'react',
+ 'react-dom',
+ '@stylexjs/stylex',
+ ]) {
+ expect(sources[name]).toBe('package-set');
+ }
+ expect(installedARelease(run.cache)).toBe(false);
+ });
+
+ /**
+ * A folder with React installed and a page of each kind.
+ * @param {Record<string, unknown>} dependencies what its package.json declares
+ */
+ function reactFolder(dependencies) {
+ const root = tempDir('react-folder');
+ writeJson(path.join(root, 'package.json'), {
+ name: 'react-folder',
+ private: true,
+ dependencies,
+ });
+ const fromCore = createRequire(
+ fileURLToPath(new URL('../../../core/package.json', import.meta.url)),
+ );
+ for (const name of ['react', 'react-dom']) {
+ const link = path.join(root, 'node_modules', name);
+ fs.mkdirSync(path.dirname(link), {recursive: true});
+ fs.symlinkSync(
+ path.dirname(fromCore.resolve(`${name}/package.json`)),
+ link,
+ 'dir',
+ );
+ }
+ fs.writeFileSync(
+ path.join(root, 'page.jsx'),
+ "import {useState} from 'react';\nimport {Button} from '@astryxdesign/core';\nexport default function Page() {\n const [label] = useState('From the set');\n return <Button label={label} />;\n}\n",
+ );
+ return root;
+ }
+
+ /**
+ * The packages a run took from the set; none when the run ended the way
+ * the bin ends one, before it could settle.
+ * @param {any} run
+ * @returns {string[]}
+ */
+ const fromSet = run =>
+ (run.result()?.packages ?? [])
+ .filter((/** @type {{source: string}} */ p) => p.source === 'package-set')
+ .map((/** @type {{name: string}} */ p) => p.name);
+
+ it('renders in a React app outside a project with the Core, React and React DOM of the set', () => {
+ const root = reactFolder({react: '*', 'react-dom': '*'});
+ const run = host({
+ argv: ['--json', 'experimental', 'render', 'page.jsx'],
+ cwd: root,
+ });
+ expect(run.status).toBe(0);
+ expect(fs.readFileSync(path.join(root, 'page.html'), 'utf-8')).toContain(
+ 'From the set',
+ );
+ expect(fromSet(run)).toEqual(
+ expect.arrayContaining(['@astryxdesign/core', 'react', 'react-dom']),
+ );
+ });
+
+ it("leaves a project's own React alone: a project that declares Core gets no package from the set", () => {
+ const root = reactFolder({
+ '@astryxdesign/core': SELF_VERSION,
+ react: '*',
+ 'react-dom': '*',
+ });
+ const run = host({
+ argv: ['--json', 'experimental', 'render', 'page.jsx'],
+ cwd: root,
+ });
+ expect(JSON.parse(run.stdout).code).toBe('ERR_RENDER_MISSING_DEPENDENCY');
+ expect(fromSet(run)).not.toContain('react');
+ expect(fromSet(run)).not.toContain('react-dom');
+ });
+
it("names a project's own integration as the project's", () => {
const root = project(tempDir(), {
'@astryxdesign/core': SELF_VERSION,
diff --git a/packages/cli/test/global-local.test.mjs b/packages/cli/test/global-local.test.mjs
index b33f1d004d..a32ac5f7c7 100644
--- a/packages/cli/test/global-local.test.mjs
+++ b/packages/cli/test/global-local.test.mjs
@@ -448,6 +448,26 @@ describe.skipIf(!POSIX)(
expect(filesIn(dir)).toEqual(before);
});
+ it("outside a project, a render whose page needs Core says the answering release's Core could not be downloaded", () => {
+ const pc = computer();
+ const g = globalCli('npm', '9.0.0', {root: pc.home});
+ const dir = tempDir('page');
+ fs.writeFileSync(
+ path.join(dir, 'page.jsx'),
+ "import {Button} from '@astryxdesign/core';\nexport default () => <Button label=\"Go\" />;\n",
+ );
+ const r = run(g.bin, ['experimental', 'render', 'page.jsx', '--json'], {
+ cwd: dir,
+ pc,
+ });
+ const error = JSON.parse(r.stdout);
+ expect(error.code).toBe('ERR_VERSIONS_UNAVAILABLE');
+ expect(error.error).toMatch(
+ /^Core 9\.0\.0 could not be (?:installed|downloaded).*\. Outside a project, commands that read Core use the Core of the release that answers; run again when the package registry can be reached\.$/u,
+ );
+ expect(fs.existsSync(path.join(dir, 'page.html'))).toBe(false);
+ });
+
it("in a fresh clone, doctor names the lockfile's Core as the daily hint and notice do", () => {
const pc = computer();
const g = globalCli('npm', '9.0.0', {root: pc.home});