Skip to content

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

TypeScript

fix(cli): `integration add theme --from` declares the packages the copied files import (#6967)

Joey07a4096fbbfd
diff --git a/.changeset/integration-add-theme-from-dependencies.md b/.changeset/integration-add-theme-from-dependencies.md
new file mode 100644
index 0000000000..21a039175e
--- /dev/null
+++ b/.changeset/integration-add-theme-from-dependencies.md
@@ -0,0 +1,9 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx integration add theme <name> --from <base>` now adds the packages the copied theme files import to `dependencies`.
+
+A fork of a bundled theme such as `neutral` copies its `icons.tsx`, which imports `lucide-react`, but the package did not declare it. So `astryx theme build` on the fork failed with "Cannot find module 'lucide-react'", and an app that installed the package hit the same error. `--from` now adds each package the copied files import, at the range the bundled themes use. It leaves out Core and React, which every Astryx app already has, and anything the package already declares.
+
+@josephfarina
diff --git a/packages/cli/api/integration/add-theme.mjs b/packages/cli/api/integration/add-theme.mjs
index 54cdab3794..ba85dfb110 100644
--- a/packages/cli/api/integration/add-theme.mjs
+++ b/packages/cli/api/integration/add-theme.mjs
@@ -10,8 +10,10 @@
*/
import * as fs from 'node:fs';
+import {isBuiltin} from 'node:module';
import * as path from 'node:path';
import {AstryxError} from '../error.mjs';
+import {CLI_ROOT} from '../../foundation/fs/paths.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
import {
assertWithin,
@@ -21,6 +23,7 @@ import {
import {
discoverBundledThemes,
discoverThemeDirectory,
+ themeFileImports,
} from '../../foundation/discovery/theme-discovery.mjs';
import {
findLocalIntegrationManifestOrNull,
@@ -214,6 +217,77 @@ function escapeRegExp(s) {
return s.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
}
+/** What every app that uses Astryx already has: Core, and React through Core's peers. */
+const APP_PROVIDED = new Set(['@astryxdesign/core', 'react', 'react-dom']);
+
+/**
+ * The npm package a module specifier names, or null for a relative path, an
+ * absolute path, or a Node built-in.
+ * @param {string} specifier
+ * @returns {string | null}
+ */
+function packageOfSpecifier(specifier) {
+ if (specifier.startsWith('.') || specifier.startsWith('/')) return null;
+ if (isBuiltin(specifier)) return null;
+ const parts = specifier.split('/');
+ return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+
+/**
+ * The npm packages a fork's copied files import that its package does not
+ * declare yet, each at the range the bundled themes are built against (the
+ * CLI's own package.json). The fork depends on them at runtime, so an app that
+ * installs the package needs them too. Derived from the imports, not copied
+ * from a base's whole dependency list. Core and React are left out, since every
+ * Astryx app has them; so is a fork of the package's own theme, whose imports
+ * the package already resolves.
+ *
+ * @param {import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme} base
+ * @param {Record<string, any>} pkg - The package's package.json.
+ * @returns {Record<string, string>} package name to range
+ */
+function forkDependencies(base, pkg) {
+ if (!base.bundled) return {};
+ /** @type {Record<string, any>} */
+ let cli;
+ try {
+ cli = JSON.parse(
+ fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf-8'),
+ );
+ } catch {
+ return {};
+ }
+ /** @type {Record<string, string>} */
+ const ranges = {
+ ...cli.devDependencies,
+ ...cli.peerDependencies,
+ ...cli.dependencies,
+ };
+ const declared = {
+ ...pkg.devDependencies,
+ ...pkg.peerDependencies,
+ ...pkg.dependencies,
+ };
+ /** @type {Record<string, string>} */
+ const needed = {};
+ for (const file of base.files) {
+ const code = /\.(?:[cm]?[jt]sx?)$/u.test(file);
+ if (!code || file.endsWith('.doc.mjs')) continue;
+ let specifiers;
+ try {
+ specifiers = themeFileImports(path.join(base.sourceDir, file));
+ } catch {
+ continue; // discovery already refuses a theme whose source does not parse
+ }
+ for (const specifier of specifiers) {
+ const name = packageOfSpecifier(specifier);
+ if (name == null || APP_PROVIDED.has(name) || name in declared) continue;
+ if (typeof ranges[name] === 'string') needed[name] = ranges[name];
+ }
+ }
+ return needed;
+}
+
/**
* Build the write plans for a forked theme.
* @param {import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme} base
@@ -467,11 +541,27 @@ export async function integrationAddTheme(name, options = {}) {
packageUpdate?.expectedOriginal ?? fs.readFileSync(packageFile);
const text = packageUpdate?.contents ?? expectedOriginal.toString('utf-8');
const current = JSON.parse(text);
- if (themesCliProblem(current) != null) {
+ let next =
+ themesCliProblem(current) != null
+ ? withCliPeer(current, THEMES_CLI)
+ : current;
+ // A fork runs the base's imports: declare the packages they come from.
+ const forked = baseTheme ? forkDependencies(baseTheme, next) : {};
+ if (Object.keys(forked).length > 0) {
+ const dependencies = {...next.dependencies, ...forked};
+ next = {
+ ...next,
+ dependencies: Object.fromEntries(
+ Object.keys(dependencies)
+ .sort()
+ .map(name => [name, dependencies[name]]),
+ ),
+ };
+ }
+ if (next !== current) {
packageUpdate = {
contents:
- JSON.stringify(withCliPeer(current, THEMES_CLI), null, 2) +
- (text.endsWith('\n') ? '\n' : ''),
+ JSON.stringify(next, null, 2) + (text.endsWith('\n') ? '\n' : ''),
expectedOriginal,
};
}
diff --git a/packages/cli/api/integration/add-theme.test.mjs b/packages/cli/api/integration/add-theme.test.mjs
index a8c8d30e56..fdf906e35d 100644
--- a/packages/cli/api/integration/add-theme.test.mjs
+++ b/packages/cli/api/integration/add-theme.test.mjs
@@ -1,8 +1,10 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {execFileSync} from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
+import {CLI_ROOT, findInstalledPackage} from '../../foundation/fs/paths.mjs';
import {integrationAddTheme} from './add-theme.mjs';
import {validateLocalIntegration} from './validate-integration.mjs';
@@ -473,6 +475,104 @@ describe('integrationAddTheme --from', () => {
).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
});
+ it('declares the npm packages the forked files import, at the range the bundled themes use', async () => {
+ setup({includeFiles: false});
+ await integrationAddTheme('ocean', {cwd: tmpDir, from: 'neutral'});
+ const pkg = JSON.parse(
+ fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+ );
+ const cli = JSON.parse(
+ fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf-8'),
+ );
+ // The copied icons.tsx imports lucide-react; Core and React are every
+ // app's own, so the fork does not declare them.
+ expect(pkg.dependencies).toEqual({
+ 'lucide-react': cli.devDependencies['lucide-react'],
+ });
+ expect(pkg.peerDependencies).toEqual({'@astryxdesign/cli': '>=0.6.4'});
+ });
+
+ it('keeps a dependency the package already declares', async () => {
+ setup({includeFiles: false});
+ const file = path.join(tmpDir, 'package.json');
+ const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+ fs.writeFileSync(
+ file,
+ `${JSON.stringify({...pkg, dependencies: {'lucide-react': '^1.0.0'}}, null, 2)}\n`,
+ );
+ await integrationAddTheme('ocean', {cwd: tmpDir, from: 'neutral'});
+ expect(JSON.parse(fs.readFileSync(file, 'utf-8')).dependencies).toEqual({
+ 'lucide-react': '^1.0.0',
+ });
+ });
+
+ it('declares nothing for a fork of a theme the package owns', async () => {
+ setup({includeFiles: false});
+ await integrationAddTheme('base', {cwd: tmpDir});
+ await integrationAddTheme('variant', {cwd: tmpDir, from: 'base'});
+ const pkg = JSON.parse(
+ fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+ );
+ expect(pkg.dependencies).toBeUndefined();
+ });
+
+ it('builds a forked neutral theme once the package installs what --from declared', async () => {
+ setup({includeFiles: false});
+ await integrationAddTheme('ocean', {cwd: tmpDir, from: 'neutral'});
+ const pkg = JSON.parse(
+ fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+ );
+ // Install exactly what the package declares, plus what every Astryx
+ // project has: Core and React.
+ for (const name of [
+ ...Object.keys(pkg.dependencies ?? {}),
+ '@astryxdesign/core',
+ 'react',
+ ]) {
+ const installed = findInstalledPackage(CLI_ROOT, name);
+ expect(installed, name).not.toBeNull();
+ const link = path.join(tmpDir, 'node_modules', ...name.split('/'));
+ fs.mkdirSync(path.dirname(link), {recursive: true});
+ fs.symlinkSync(
+ fs.realpathSync(/** @type {string} */ (installed)),
+ link,
+ 'dir',
+ );
+ }
+ // A separate process without NODE_PATH, so only what the package
+ // installed can resolve.
+ let status = 0;
+ let output = '';
+ try {
+ execFileSync(
+ process.execPath,
+ [
+ path.join(CLI_ROOT, 'clients/cli/bin/astryx.mjs'),
+ 'theme',
+ 'build',
+ 'themes/ocean/oceanTheme.ts',
+ ],
+ {
+ cwd: tmpDir,
+ env: {...process.env, NODE_PATH: ''},
+ encoding: 'utf-8',
+ stdio: 'pipe',
+ },
+ );
+ } catch (error) {
+ const failure = /** @type {any} */ (error);
+ status = failure.status ?? 1;
+ output = `${failure.stdout ?? ''}${failure.stderr ?? ''}`;
+ }
+ expect({status, output: status === 0 ? '' : output}).toEqual({
+ status: 0,
+ output: '',
+ });
+ expect(fs.existsSync(path.join(tmpDir, 'themes/ocean/ocean.css'))).toBe(
+ true,
+ );
+ });
+
it('works with different bundled themes', async () => {
setup();
const result = await integrationAddTheme('dusk', {
diff --git a/packages/cli/api/integration/integrationAddTheme.doc.mjs b/packages/cli/api/integration/integrationAddTheme.doc.mjs
index 83eb6a005a..04db3ad2d3 100644
--- a/packages/cli/api/integration/integrationAddTheme.doc.mjs
+++ b/packages/cli/api/integration/integrationAddTheme.doc.mjs
@@ -37,7 +37,7 @@ export const doc = {
name: 'options.from',
type: 'string',
description:
- 'Slug of an existing theme to fork as the starting point. The new theme copies the base and has no link back.',
+ 'Slug of an existing theme to fork as the starting point. The new theme copies the base and has no link back, and package.json `dependencies` gains the npm packages the copied files import (other than Core and React).',
},
],
returns: [
diff --git a/packages/cli/assets/docs/tree/add-a-theme.doc.mjs b/packages/cli/assets/docs/tree/add-a-theme.doc.mjs
index 1c87b7f0ab..4ce5fdc618 100644
--- a/packages/cli/assets/docs/tree/add-a-theme.doc.mjs
+++ b/packages/cli/assets/docs/tree/add-a-theme.doc.mjs
@@ -65,6 +65,10 @@ Declare theme root ./themes in astryx.integration.mjs.
lang: 'bash',
code: 'npx astryx integration add theme ocean --from neutral',
},
+ {
+ type: 'prose',
+ text: 'The copy keeps the packages the base theme uses, such as `lucide-react` for its icons: `--from` adds them to your `dependencies`, so an app that installs your package gets them too. Install your dependencies again before you build the theme.',
+ },
{
type: 'prose',
text: 'Use `--from` when you want to change a lot. For a small change that should stay linked to a base theme, use `extends` instead ({@link generic:define-the-theme}).',
diff --git a/packages/cli/clients/cli/commands/integration-add.doc.mjs b/packages/cli/clients/cli/commands/integration-add.doc.mjs
index 6838909a0b..3c06f38252 100644
--- a/packages/cli/clients/cli/commands/integration-add.doc.mjs
+++ b/packages/cli/clients/cli/commands/integration-add.doc.mjs
@@ -60,7 +60,7 @@ export const doc = {
flag: '--from <theme>',
param: 'options.from',
description:
- 'Existing theme slug to fork as a starting point instead of a blank scaffold; the new theme copies the base and has no link back. Only valid for theme',
+ 'Existing theme slug to fork as a starting point instead of a blank scaffold; the new theme copies the base and has no link back, and package.json `dependencies` gains the npm packages the copied files import (other than Core and React). Only valid for theme',
},
{
flag: '--to <version>',
diff --git a/packages/cli/foundation/discovery/theme-discovery.mjs b/packages/cli/foundation/discovery/theme-discovery.mjs
index 532e70fab1..bd47313f1e 100644
--- a/packages/cli/foundation/discovery/theme-discovery.mjs
+++ b/packages/cli/foundation/discovery/theme-discovery.mjs
@@ -200,6 +200,15 @@ function moduleSpecifiers(file, jscodeshift) {
return specifiers;
}
+/**
+ * Every module a theme source file imports or re-exports, as written.
+ * @param {string} file
+ * @returns {string[]}
+ */
+export function themeFileImports(file) {
+ return moduleSpecifiers(file, sourceParser());
+}
+
/**
* Validate that every local static dependency is copied with the theme.
* @param {string} file