Skip to content

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

TypeScript

fix(themes,cli): gate theme dists with check-fully-specified and pin --icons-specifier coverage (#4625)

AK8b07cb95244b
diff --git a/.changeset/theme-built-entry-node-esm.md b/.changeset/theme-built-entry-node-esm.md
new file mode 100644
index 0000000000..67bdf848b6
--- /dev/null
+++ b/.changeset/theme-built-entry-node-esm.md
@@ -0,0 +1,12 @@
+---
+'@astryxdesign/theme-butter': patch
+'@astryxdesign/theme-chocolate': patch
+'@astryxdesign/theme-gothic': patch
+'@astryxdesign/theme-matcha': patch
+'@astryxdesign/theme-neutral': patch
+'@astryxdesign/theme-stone': patch
+'@astryxdesign/theme-y2k': patch
+---
+
+[fix] The `/built` entry now loads under Node ESM and externalized SSR (Vite `--ssr`, Remix / React Router v7): it imports `./icons.mjs` instead of the extensionless `./icons` Node cannot resolve.
+@AKnassa
diff --git a/packages/cli/api/theme/build/build.icons-specifier.test.mjs b/packages/cli/api/theme/build/build.icons-specifier.test.mjs
new file mode 100644
index 0000000000..054f0ce863
--- /dev/null
+++ b/packages/cli/api/theme/build/build.icons-specifier.test.mjs
@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Direct-API tests for `themeBuild`'s `iconsSpecifier` option (#4620).
+ *
+ * The CLI surface of `--icons-specifier` is pinned in
+ * clients/cli/commands/build-theme.icons-specifier.test.mjs; these tests pin
+ * the programmatic surface that watch mode, editor tooling, and build scripts
+ * call directly: the option reaches the emitted module, its absence leaves the
+ * scraped specifier byte-for-byte alone, and `check` mode compares the
+ * specifier-bearing text like any other generated byte — outputs built with a
+ * different specifier than the one being checked against are stale, not clean.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {themeBuild} from './build.mjs';
+
+let tmpDir;
+beforeEach(() => {
+ tmpDir = fs.mkdtempSync(
+ path.join(os.tmpdir(), 'astryx-api-icons-specifier-'),
+ );
+});
+afterEach(() => {
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * Write a theme source (plus a loadable icons source beside it) under
+ * `<tmpDir>/src/`. The registry is a plain object — the emit path only
+ * re-exports it, so no React is needed.
+ */
+function writeIconTheme({withIcons = true, name = 'icotheme'} = {}) {
+ const srcDir = path.join(tmpDir, 'src');
+ fs.mkdirSync(srcDir, {recursive: true});
+ fs.writeFileSync(
+ path.join(srcDir, 'icons.ts'),
+ `export const myIcons = { close: 'x' };\n`,
+ );
+ const iconLines = withIcons ? [`import { myIcons } from './icons';`] : [];
+ fs.writeFileSync(
+ path.join(srcDir, `${name}.ts`),
+ [
+ ...iconLines,
+ `export default { name: '${name}', tokens: { '--color-bg': '#fff' }${
+ withIcons ? ', icons: myIcons' : ''
+ } };`,
+ '',
+ ].join('\n'),
+ );
+ return `src/${name}.ts`;
+}
+
+function builtModule(name = 'icotheme') {
+ return fs.readFileSync(path.join(tmpDir, 'dist', `${name}.js`), 'utf8');
+}
+
+describe('themeBuild({iconsSpecifier}) — direct API', () => {
+ it('emits the declared specifier into the generated module', async () => {
+ const file = writeIconTheme();
+
+ const result = await themeBuild(
+ file,
+ {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},
+ {cwd: tmpDir},
+ );
+
+ expect(result?.type).toBe('theme.build');
+ const js = builtModule();
+ expect(js).toContain(`import { myIcons } from "./icons.mjs";`);
+ // The registry re-export survives the override.
+ expect(js).toContain('export { myIcons }');
+ });
+
+ it('emits the scraped specifier unchanged when the option is omitted', async () => {
+ const file = writeIconTheme();
+
+ const result = await themeBuild(
+ file,
+ {out: 'dist/theme.css'},
+ {cwd: tmpDir},
+ );
+
+ expect(result?.type).toBe('theme.build');
+ expect(builtModule()).toContain(`import { myIcons } from './icons';`);
+ });
+
+ it('is inert for a theme with no icons field', async () => {
+ const file = writeIconTheme({withIcons: false});
+
+ const result = await themeBuild(
+ file,
+ {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},
+ {cwd: tmpDir},
+ );
+
+ expect(result?.type).toBe('theme.build');
+ // The header comment's usage example mentions imports; only a real
+ // statement (line-leading `import`) would be a leak.
+ const js = builtModule();
+ expect(js).not.toMatch(/^import /m);
+ expect(js).not.toContain('icons.mjs');
+ });
+
+ it('check mode is clean against outputs built with the same specifier', async () => {
+ const file = writeIconTheme();
+ await themeBuild(
+ file,
+ {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},
+ {cwd: tmpDir},
+ );
+
+ const result = await themeBuild(
+ file,
+ {out: 'dist/theme.css', check: true, iconsSpecifier: './icons.mjs'},
+ {cwd: tmpDir},
+ );
+
+ expect(result?.type).toBe('theme.build.check');
+ expect(result?.data.upToDate).toBe(true);
+ expect(result?.data.stale).toEqual([]);
+ });
+
+ it('check mode reports outputs stale when the specifier differs', async () => {
+ const file = writeIconTheme();
+ await themeBuild(
+ file,
+ {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},
+ {cwd: tmpDir},
+ );
+
+ // Checking without the option regenerates with the scraped './icons' —
+ // different bytes than the on-disk module, so the check must flag it.
+ const result = await themeBuild(
+ file,
+ {out: 'dist/theme.css', check: true},
+ {cwd: tmpDir},
+ );
+
+ expect(result?.type).toBe('theme.build.check');
+ expect(result?.data.upToDate).toBe(false);
+ expect(result?.data.stale.some(entry => entry.reason === 'outdated')).toBe(
+ true,
+ );
+ });
+});
diff --git a/packages/cli/clients/cli/commands/build-theme.icons-specifier.test.mjs b/packages/cli/clients/cli/commands/build-theme.icons-specifier.test.mjs
index c130d9dfc4..0768a5177f 100644
--- a/packages/cli/clients/cli/commands/build-theme.icons-specifier.test.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.icons-specifier.test.mjs
@@ -15,15 +15,34 @@
* declared rather than inferred. Absent the flag, output is byte-for-byte what
* it was before, which keeps the default no-`--out` flow — where the neighbour
* is an uncompiled `icons.tsx` that only a bundler can resolve — working.
+ *
+ * The spawned-process block at the bottom pins what only real processes can
+ * prove: the emitted module actually loads under Node ESM, and the watch
+ * loop's child re-invocations carry the flag to every rebuild.
*/
import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import {spawn, spawnSync} from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
+import {fileURLToPath, pathToFileURL} from 'node:url';
import {ensureCoreBuilt} from './ensure-core-built.mjs';
import {runCli} from '../../../test-utils/run-cli.mjs';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../bin/astryx.mjs');
+
+/** Poll until `predicate()` is true or the timeout elapses. */
+async function waitFor(predicate, {timeout = 20000, interval = 100} = {}) {
+ const start = Date.now();
+ for (;;) {
+ if (predicate()) return true;
+ if (Date.now() - start > timeout) return false;
+ await new Promise(r => setTimeout(r, interval));
+ }
+}
+
/**
* The emitted icon import, or null. Reads the statement rather than the whole
* file: the `@generated` header quotes the source filename and a usage example,
@@ -142,13 +161,7 @@ describe('theme build --icons-specifier', () => {
const relativeTheme = path.relative(project, themeFile);
const built = await runCli(
- [
- 'theme',
- 'build',
- relativeTheme,
- '--icons-specifier',
- './icons.mjs',
- ],
+ ['theme', 'build', relativeTheme, '--icons-specifier', './icons.mjs'],
project,
);
expect(built.code).toBe(0);
@@ -223,3 +236,114 @@ describe('theme build --icons-specifier', () => {
expect(generated).not.toContain('icons:');
});
});
+
+describe('theme build --icons-specifier (spawned processes)', () => {
+ it('emits a module Node can actually load', async () => {
+ const project = path.join(tmpDir, 'project');
+ const themeFile = writeThemeWithIcons(project, 'loadable');
+
+ const result = await runCli(
+ [
+ 'theme',
+ 'build',
+ path.relative(project, themeFile),
+ '--icons-specifier',
+ './icons.mjs',
+ ],
+ project,
+ );
+ expect(result.code).toBe(0);
+
+ // The text assertions above prove the emitted line; only a real Node
+ // process proves the module resolves and evaluates. That distinction is
+ // the regression #4620 shipped: every byte existed, none of them loaded.
+ const builtUrl = pathToFileURL(path.join(project, 'loadable.js'));
+ const probe = spawnSync(
+ process.execPath,
+ [
+ '--input-type=module',
+ '-e',
+ `const m = await import(${JSON.stringify(builtUrl.href)});` +
+ `if (m.loadableTheme?.name !== 'loadable') throw new Error('bad theme export');` +
+ `if (typeof m.testIcons !== 'object') throw new Error('bad registry export');`,
+ ],
+ {encoding: 'utf8'},
+ );
+ expect(probe.stderr).toBe('');
+ expect(probe.status).toBe(0);
+ });
+
+ it('watch mode forwards the flag to every rebuild', async () => {
+ const project = path.join(tmpDir, 'project');
+ const themeFile = writeThemeWithIcons(project, 'watched');
+ const cssFile = path.join(project, 'out', 'theme.css');
+ const builtFile = path.join(project, 'out', 'watched.js');
+ const declaredImport = 'import { testIcons } from "./icons.mjs";';
+
+ const child = spawn(
+ process.execPath,
+ [
+ CLI_BIN,
+ 'theme',
+ 'build',
+ path.relative(project, themeFile),
+ '--out',
+ 'out/theme.css',
+ '--icons-specifier',
+ './icons.mjs',
+ '--watch',
+ ],
+ {cwd: project, env: {...process.env, FORCE_COLOR: '0'}},
+ );
+ let output = '';
+ child.stdout.on('data', d => (output += d.toString()));
+ child.stderr.on('data', d => (output += d.toString()));
+
+ try {
+ // Initial build: the declared specifier reaches the module.
+ expect(await waitFor(() => fs.existsSync(cssFile))).toBe(true);
+ expect(await waitFor(() => /Watching/i.test(output))).toBe(true);
+ expect(iconImportLine(fs.readFileSync(builtFile, 'utf8'))).toBe(
+ declaredImport,
+ );
+
+ // Rebuilds run through a child re-invocation of `theme build`, so the
+ // flag reaches them only if the watch loop forwards it. Change a token
+ // and wait for the rebuilt CSS. fs.watch delivery is best-effort under
+ // load, so re-touch until the rebuild shows up (idempotent write).
+ const touched =
+ `import {testIcons} from './icons';\n` +
+ `export default {\n` +
+ ` name: "watched",\n` +
+ ` icons: testIcons,\n` +
+ ` tokens: {'--color-bg': '#0a0b0c'},\n` +
+ `};\n`;
+ fs.writeFileSync(themeFile, touched);
+ const rebuilt = await waitFor(() => {
+ try {
+ if (fs.readFileSync(cssFile, 'utf-8').includes('#0a0b0c'))
+ return true;
+ } catch {
+ // CSS mid-write; fall through to re-touch.
+ }
+ try {
+ fs.writeFileSync(themeFile, touched);
+ } catch {
+ // Retried on the next poll.
+ }
+ return false;
+ });
+ expect(rebuilt).toBe(true);
+
+ // The regenerated module still carries the declared specifier — the
+ // forwarding is what this test pins. A watch loop that dropped the flag
+ // would regenerate with the scraped './icons' here and ship the #4620
+ // bytes on every save.
+ expect(iconImportLine(fs.readFileSync(builtFile, 'utf8'))).toBe(
+ declaredImport,
+ );
+ } finally {
+ child.kill('SIGINT');
+ }
+ }, 60_000);
+});
diff --git a/packages/themes/butter/package.json b/packages/themes/butter/package.json
index a8a8cb2f6e..7489d85ae4 100644
--- a/packages/themes/butter/package.json
+++ b/packages/themes/butter/package.json
@@ -46,7 +46,7 @@
"src"
],
"scripts": {
- "build": "astryx theme build src/butterTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"
+ "build": "astryx theme build src/butterTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"
},
"dependencies": {
"lucide-react": "^1.18.0"
diff --git a/packages/themes/chocolate/package.json b/packages/themes/chocolate/package.json
index f26b62b5b8..4b37009e3e 100644
--- a/packages/themes/chocolate/package.json
+++ b/packages/themes/chocolate/package.json
@@ -46,7 +46,7 @@
"src"
],
"scripts": {
- "build": "astryx theme build src/chocolateTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"
+ "build": "astryx theme build src/chocolateTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"
},
"dependencies": {
"lucide-react": "^1.18.0"
diff --git a/packages/themes/gothic/package.json b/packages/themes/gothic/package.json
index e2dccf07c8..789ca5a474 100644
--- a/packages/themes/gothic/package.json
+++ b/packages/themes/gothic/package.json
@@ -46,7 +46,7 @@
"src"
],
"scripts": {
- "build": "astryx theme build src/gothicTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"
+ "build": "astryx theme build src/gothicTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"
},
"dependencies": {
"lucide-react": "^1.18.0"
diff --git a/packages/themes/matcha/package.json b/packages/themes/matcha/package.json
index 888313d7e9..e2ee53b2f6 100644
--- a/packages/themes/matcha/package.json
+++ b/packages/themes/matcha/package.json
@@ -45,7 +45,7 @@
"src"
],
"scripts": {
- "build": "astryx theme build src/matchaTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"
+ "build": "astryx theme build src/matchaTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"
},
"dependencies": {
"lucide-react": "^1.18.0"
diff --git a/packages/themes/neutral/package.json b/packages/themes/neutral/package.json
index 3c5026bbbf..6689692278 100644
--- a/packages/themes/neutral/package.json
+++ b/packages/themes/neutral/package.json
@@ -46,7 +46,7 @@
"src"
],
"scripts": {
- "build": "astryx theme build src/neutralTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"
+ "build": "astryx theme build src/neutralTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"
},
"dependencies": {
"lucide-react": "^1.18.0"
diff --git a/packages/themes/stone/package.json b/packages/themes/stone/package.json
index ac0bcb331a..1109fd6c98 100644
--- a/packages/themes/stone/package.json
+++ b/packages/themes/stone/package.json
@@ -46,7 +46,7 @@
"src"
],
"scripts": {
- "build": "astryx theme build src/stoneTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"
+ "build": "astryx theme build src/stoneTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"
},
"dependencies": {
"lucide-react": "^1.18.0"
diff --git a/packages/themes/y2k/package.json b/packages/themes/y2k/package.json
index bc708b6da8..84916a4731 100644
--- a/packages/themes/y2k/package.json
+++ b/packages/themes/y2k/package.json
@@ -46,7 +46,7 @@
"src"
],
"scripts": {
- "build": "astryx theme build src/y2kTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"
+ "build": "astryx theme build src/y2kTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"
},
"dependencies": {
"lucide-react": "^1.18.0"