Skip to content

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

TypeScript

docs: document the StyleX peer dependency in README and astryx init (#4514)

Xinzi Zhouf65abab1881e
diff --git a/.changeset/docs-install-peer-dependencies.md b/.changeset/docs-install-peer-dependencies.md
new file mode 100644
index 0000000000..9c600145c5
--- /dev/null
+++ b/.changeset/docs-install-peer-dependencies.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+'@astryxdesign/cli': patch
+---
+
+[docs] Document the `@astryxdesign/core` StyleX peer dependency — add `@stylexjs/stylex` to the Getting Started / Quick Start install commands in both READMEs, and add an `astryx init` next-steps reminder to ensure the `@stylexjs/stylex` peer dependency is met, with a pointer to `astryx doctor`. StyleX is the styling runtime every component calls, and not all package managers auto-install peers.
+
+@imdreamrunner
diff --git a/.changeset/fix-doctor-scoped-peer-install.md b/.changeset/fix-doctor-scoped-peer-install.md
new file mode 100644
index 0000000000..82324454c7
--- /dev/null
+++ b/.changeset/fix-doctor-scoped-peer-install.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx doctor`'s peer-dependency check is now version-aware and names scoped packages correctly. Two problems are fixed: (1) the install hint was built with `name.split('@')[0]`, which for a scoped peer like `@stylexjs/stylex` returned an empty string, printing a bare `npm install ` with no package; and (2) the check only verified a peer was _present_, not that its installed version satisfied the declared range — so an out-of-range version (e.g. `@stylexjs/[email protected]` against a `^0.19.0` peer) was reported as satisfied. The check now flags out-of-range peers and its fix pins the required range, e.g. `npm install @stylexjs/stylex@^0.19.0`.
+
+@imdreamrunner
diff --git a/README.md b/README.md
index b3cd0bb68b..25c00e232b 100644
--- a/README.md
+++ b/README.md
@@ -39,19 +39,19 @@ It ships 150+ accessible components, brand-level theming, dark mode, ready-to-sh
Astryx requires **React 19** or later (`react` and `react-dom` are peer dependencies of `@astryxdesign/core`).
-Install Astryx and a theme:
+Install Astryx, a theme, and its peer dependencies:
```bash
# npm
-npm install @astryxdesign/core @astryxdesign/theme-neutral
+npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
npm install -D @astryxdesign/cli
# pnpm
-pnpm add @astryxdesign/core @astryxdesign/theme-neutral
+pnpm add @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
pnpm add -D @astryxdesign/cli
# yarn
-yarn add @astryxdesign/core @astryxdesign/theme-neutral
+yarn add @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
yarn add -D @astryxdesign/cli
```
diff --git a/packages/cli/api/doctor/doctor.mjs b/packages/cli/api/doctor/doctor.mjs
index c45d0ab4fd..897bb9c377 100644
--- a/packages/cli/api/doctor/doctor.mjs
+++ b/packages/cli/api/doctor/doctor.mjs
@@ -28,7 +28,7 @@ import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../foundation/env/nod
import {CLI_ROOT, findCoreDir} from '../../foundation/fs/paths.mjs';
import {detectPackageManager, getCliInvocation} from '../../foundation/env/package-manager.mjs';
import {findConfigPath, Project} from '../../foundation/config/project.mjs';
-import {semverCompare, isValidSemver} from '../../foundation/env/semver.mjs';
+import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env/semver.mjs';
const _require = createRequire(import.meta.url);
@@ -436,30 +436,53 @@ export function checkPeerDeps(ctx) {
}
const missing = [];
+ /** @type {Array<{name: string, want: string, have: string}>} */
+ const mismatched = [];
for (const name of peerNames) {
- let present = false;
+ const want = peers[name];
+ let pkgJsonPath;
try {
- _require.resolve(`${name}/package.json`, {paths: [ctx.cwd]});
- present = true;
+ pkgJsonPath = _require.resolve(`${name}/package.json`, {paths: [ctx.cwd]});
} catch {
- // Some packages don't expose package.json — try resolving the entry.
+ // package.json isn't exported — fall back to entry resolution for
+ // presence only (we then can't read the version to range-check it).
try {
_require.resolve(name, {paths: [ctx.cwd]});
- present = true;
} catch {
- // Still unresolved — leave present at its initial false.
+ missing.push(`${name}@${want}`);
}
+ continue;
+ }
+ // Present and version-readable: verify it actually satisfies the range,
+ // not just that the package exists (a bare `npm install` can resolve an
+ // out-of-range version from a stale consumer range and still "look" fine).
+ const have = pkgVersion(path.dirname(pkgJsonPath));
+ if (have && !satisfiesRange(have, want)) {
+ mismatched.push({name, want, have});
}
- if (!present) missing.push(`${name}@${peers[name]}`);
}
- if (missing.length > 0) {
+ if (missing.length > 0 || mismatched.length > 0) {
+ const problems = [];
+ if (missing.length) problems.push(`missing: ${missing.join(', ')}`);
+ if (mismatched.length) {
+ problems.push(
+ `out of range: ${mismatched
+ .map(m => `${m.name}@${m.have} (needs ${m.want})`)
+ .join(', ')}`,
+ );
+ }
+ // Pin the required range for anything wrong so the hint fixes it even when a
+ // stale consumer range would otherwise resolve an incompatible version.
+ // Quote targets containing shell metacharacters (e.g. `react@>=19.0.0`).
+ const quote = (/** @type {string} */ s) => (/[<>|() ]/.test(s) ? `'${s}'` : s);
+ const targets = [...missing, ...mismatched.map(m => `${m.name}@${m.want}`)].map(quote);
return {
id: 'peer-deps',
label: '@astryxdesign/core peer dependencies',
status: 'warn',
- message: `Missing peer dependencies: ${missing.join(', ')}.`,
- fix: `Install the required peers, e.g. \`npm install ${missing.map(m => m.split('@')[0]).join(' ')}\`.`,
+ message: `Peer dependency issues — ${problems.join('; ')}.`,
+ fix: `Install compatible peers: \`npm install ${targets.join(' ')}\`.`,
};
}
diff --git a/packages/cli/api/init/run/run.mjs b/packages/cli/api/init/run/run.mjs
index db93d8cb49..e95adda6a6 100644
--- a/packages/cli/api/init/run/run.mjs
+++ b/packages/cli/api/init/run/run.mjs
@@ -44,15 +44,17 @@ export function getNextSteps(invocation) {
return [
'',
' Next steps:',
- " 1. Import base styles: import '@astryxdesign/core/reset.css'",
+ ' 1. Ensure the @stylexjs/stylex peer dependency is met',
+ ` (run \`${invocation} doctor\` to verify)`,
+ " 2. Import base styles: import '@astryxdesign/core/reset.css'",
" and import '@astryxdesign/core/astryx.css'",
- " 2. Import components: import { Button } from '@astryxdesign/core'",
- ' 3. Optionally add a theme (use the pre-built path for performance):',
+ " 3. Import components: import { Button } from '@astryxdesign/core'",
+ ' 4. Optionally add a theme (use the pre-built path for performance):',
" import { neutralTheme } from '@astryxdesign/theme-neutral/built'",
" import '@astryxdesign/theme-neutral/theme.css'",
' <Theme theme={neutralTheme}>...</Theme>',
` For custom themes, run \`${invocation} theme build <file>\` to generate the built artifacts.`,
- ` 4. ${invocation} --help for all commands`,
+ ` 5. ${invocation} --help for all commands`,
'',
];
}
diff --git a/packages/cli/clients/cli/commands/doctor.test.mjs b/packages/cli/clients/cli/commands/doctor.test.mjs
index 469181a525..49e7421c84 100644
--- a/packages/cli/clients/cli/commands/doctor.test.mjs
+++ b/packages/cli/clients/cli/commands/doctor.test.mjs
@@ -247,6 +247,35 @@ describe('doctor — individual checks', () => {
expect(res.status).toBe('pass');
});
+ it('peer-deps: fix names a scoped missing peer (no empty install command)', () => {
+ const coreDir = installCore('0.0.14', {'@stylexjs/stylex': '^0.19.0'});
+ const res = checkPeerDeps({cwd: tmpDir, coreDir});
+ expect(res.status).toBe('warn');
+ // The scope must survive version-stripping — `split('@')[0]` used to drop it,
+ // leaving a bare `npm install ` with no package name.
+ expect(res.fix).toContain('npm install @stylexjs/stylex');
+ expect(res.fix).not.toMatch(/npm install\s*`/);
+ });
+
+ it('peer-deps: WARN when an installed peer is out of the declared range', () => {
+ const coreDir = installCore('0.0.14', {'@stylexjs/stylex': '^0.19.0'});
+ // Present, but a stale range resolved an incompatible version.
+ installPkg('@stylexjs/stylex', '0.10.1');
+ const res = checkPeerDeps({cwd: tmpDir, coreDir});
+ expect(res.status).toBe('warn');
+ expect(res.message).toContain('0.10.1');
+ expect(res.message).toContain('^0.19.0');
+ // The fix pins the required range so it overrides the stale one.
+ expect(res.fix).toContain('@stylexjs/stylex@^0.19.0');
+ });
+
+ it('peer-deps: PASS when an installed peer satisfies the range', () => {
+ const coreDir = installCore('0.0.14', {'@stylexjs/stylex': '^0.19.0'});
+ installPkg('@stylexjs/stylex', '0.19.2');
+ const res = checkPeerDeps({cwd: tmpDir, coreDir});
+ expect(res.status).toBe('pass');
+ });
+
it('package-manager: INFO, reports yarn from lockfile', () => {
fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), '');
const res = checkPackageManager({cwd: tmpDir});
diff --git a/packages/cli/foundation/env/semver.mjs b/packages/cli/foundation/env/semver.mjs
index b5ec05d444..39c0e9f208 100644
--- a/packages/cli/foundation/env/semver.mjs
+++ b/packages/cli/foundation/env/semver.mjs
@@ -70,3 +70,95 @@ export function semverGte(a, b) {
export function semverGt(a, b) {
return semverCompare(a, b) > 0;
}
+
+/**
+ * Parse a (possibly partial) version like `1`, `1.2`, or `1.2.3` into numeric
+ * parts — missing components default to 0, and `count` records how many were
+ * actually given (so `^0.10` can be told apart from `^0.10.0`).
+ *
+ * @param {string} value
+ * @returns {{major: number, minor: number, patch: number, count: number}}
+ */
+function parseVersionParts(value) {
+ const core = String(value).trim().replace(/^[v=]+/, '').split(/[-+]/)[0];
+ const nums = core.split('.').map(n => parseInt(n, 10));
+ return {
+ major: Number.isFinite(nums[0]) ? nums[0] : 0,
+ minor: Number.isFinite(nums[1]) ? nums[1] : 0,
+ patch: Number.isFinite(nums[2]) ? nums[2] : 0,
+ count: nums.filter(n => Number.isFinite(n)).length,
+ };
+}
+
+/**
+ * `true` if `version` satisfies a single comparator token (`^1.2.3`, `~1.2`,
+ * `>=1.0.0`, `<2.0.0`, `=1.2.3`, or a bare `1.2.3`). An unrecognized token
+ * returns `true` (treated as "no constraint") so callers never emit a false
+ * mismatch on input this minimal parser doesn't model.
+ *
+ * @param {string} version
+ * @param {string} token
+ * @returns {boolean}
+ */
+function satisfiesComparator(version, token) {
+ const m = /^(\^|~|>=|<=|>|<|=)?\s*(.*)$/.exec(token.trim());
+ if (!m) return true;
+ const op = m[1] || '=';
+ const target = m[2].trim();
+ if (target === '' || target === '*' || target.toLowerCase() === 'x') return true;
+ const t = parseVersionParts(target);
+ // No numeric component (e.g. `workspace:*`, a git/url spec) — can't model it,
+ // so treat as unconstrained rather than emit a false mismatch.
+ if (t.count === 0) return true;
+ const cmp = semverCompare(version, `${t.major}.${t.minor}.${t.patch}`);
+ const below = (/** @type {string} */ upper) =>
+ cmp >= 0 && semverCompare(version, upper) < 0;
+ switch (op) {
+ case '>=':
+ return cmp >= 0;
+ case '>':
+ return cmp > 0;
+ case '<=':
+ return cmp <= 0;
+ case '<':
+ return cmp < 0;
+ case '^':
+ if (t.major > 0) return below(`${t.major + 1}.0.0`);
+ if (t.minor > 0) return below(`0.${t.minor + 1}.0`);
+ return below(`0.0.${t.patch + 1}`);
+ case '~':
+ return below(t.count >= 2 ? `${t.major}.${t.minor + 1}.0` : `${t.major + 1}.0.0`);
+ case '=':
+ default:
+ // A full version is exact; a partial (`1`, `1.2`) behaves like a range.
+ if (t.count >= 3) return cmp === 0;
+ return below(t.count === 2 ? `${t.major}.${t.minor + 1}.0` : `${t.major + 1}.0.0`);
+ }
+}
+
+/**
+ * Minimal semver range-satisfaction check covering the range forms Astryx peers
+ * use: exact, caret (`^`), tilde (`~`), comparators (`>=` `>` `<=` `<` `=`),
+ * partial versions (`^0.10`), the wildcards `*` / `x` / empty, and `||`-joined
+ * unions of space-joined intersections (`>=1 <2`).
+ *
+ * Returns `true` when `version` satisfies `range`. On a non-semver `version` or a
+ * range this parser can't confidently model, returns `true` — the peer-dep check
+ * only acts on a *confident* mismatch, so an unparseable range never becomes a
+ * false warning.
+ *
+ * @param {string} version installed version (MAJOR.MINOR.PATCH)
+ * @param {string} range a peerDependencies range
+ * @returns {boolean}
+ */
+export function satisfiesRange(version, range) {
+ if (!isValidSemver(version)) return true;
+ const r = String(range ?? '').trim();
+ if (r === '' || r === '*' || r.toLowerCase() === 'x' || r.toLowerCase() === 'latest') {
+ return true;
+ }
+ return r.split('||').some(union => {
+ const tokens = union.trim().split(/\s+/).filter(Boolean);
+ return tokens.length === 0 || tokens.every(tok => satisfiesComparator(version, tok));
+ });
+}
diff --git a/packages/cli/foundation/env/semver.test.mjs b/packages/cli/foundation/env/semver.test.mjs
index fa7f00a263..8a2ad15129 100644
--- a/packages/cli/foundation/env/semver.test.mjs
+++ b/packages/cli/foundation/env/semver.test.mjs
@@ -1,7 +1,13 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {describe, it, expect} from 'vitest';
-import {isValidSemver, semverCompare, semverGt, semverGte} from './semver.mjs';
+import {
+ isValidSemver,
+ satisfiesRange,
+ semverCompare,
+ semverGt,
+ semverGte,
+} from './semver.mjs';
describe('semverCompare', () => {
it('orders patch versions numerically (not lexicographically)', () => {
@@ -65,3 +71,41 @@ describe('isValidSemver', () => {
expect(isValidSemver(123)).toBe(false);
});
});
+
+describe('satisfiesRange', () => {
+ it('handles caret ranges, including 0.x semantics', () => {
+ expect(satisfiesRange('0.19.0', '^0.19.0')).toBe(true);
+ expect(satisfiesRange('0.19.2', '^0.19.0')).toBe(true);
+ // 0.x caret is locked to the minor — the peer-dep bug that motivated this.
+ expect(satisfiesRange('0.10.1', '^0.19.0')).toBe(false);
+ expect(satisfiesRange('0.20.0', '^0.19.0')).toBe(false);
+ // major > 0 caret allows any minor/patch below the next major.
+ expect(satisfiesRange('1.5.0', '^1.2.0')).toBe(true);
+ expect(satisfiesRange('2.0.0', '^1.2.0')).toBe(false);
+ });
+
+ it('handles comparators and partial versions', () => {
+ expect(satisfiesRange('19.0.0', '>=19.0.0')).toBe(true);
+ expect(satisfiesRange('20.1.0', '>=19.0.0')).toBe(true);
+ expect(satisfiesRange('18.2.0', '>=19.0.0')).toBe(false);
+ expect(satisfiesRange('0.10.5', '^0.10')).toBe(true);
+ expect(satisfiesRange('0.11.0', '^0.10')).toBe(false);
+ });
+
+ it('handles exact, tilde, unions, and wildcards', () => {
+ expect(satisfiesRange('1.2.3', '1.2.3')).toBe(true);
+ expect(satisfiesRange('1.2.4', '1.2.3')).toBe(false);
+ expect(satisfiesRange('1.2.9', '~1.2.0')).toBe(true);
+ expect(satisfiesRange('1.3.0', '~1.2.0')).toBe(false);
+ expect(satisfiesRange('16.14.0', '>=16 <18 || >=19')).toBe(true);
+ expect(satisfiesRange('18.0.0', '>=16 <18 || >=19')).toBe(false);
+ expect(satisfiesRange('19.0.0', '*')).toBe(true);
+ });
+
+ it('never emits a false mismatch on non-semver input or unparseable ranges', () => {
+ expect(satisfiesRange('not-a-version', '^0.19.0')).toBe(true);
+ expect(satisfiesRange('0.10.1', '')).toBe(true);
+ expect(satisfiesRange('0.10.1', 'latest')).toBe(true);
+ expect(satisfiesRange('0.10.1', 'workspace:*')).toBe(true);
+ });
+});
diff --git a/packages/core/README.md b/packages/core/README.md
index 367aec9f33..9c56337ab6 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -80,7 +80,7 @@ Astryx requires **React 19** or later (`react` and `react-dom` >= 19.0.0 are pee
Install Astryx and a theme:
```bash
-npm install @astryxdesign/core @astryxdesign/theme-neutral
+npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
```
Then pick your setup below based on your framework and styling approach.
@@ -228,7 +228,7 @@ export default function Page() {
Use the pre-built dist alongside StyleX for your own styles.
```bash
-npm install @astryxdesign/core @astryxdesign/theme-neutral
+npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
```
**`src/app/globals.css`**
@@ -244,7 +244,7 @@ Providers and layout are the same as the Tailwind example (use `@astryxdesign/th
### Vite
```bash
-npm install @astryxdesign/core @astryxdesign/theme-neutral
+npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
```
Same CSS imports and providers as above. No build plugins needed; Astryx ships pre-built.