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.mdnew file mode 100644index 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.++@imdreamrunnerdiff --git a/.changeset/fix-doctor-scoped-peer-install.md b/.changeset/fix-doctor-scoped-peer-install.mdnew file mode 100644index 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`.++@imdreamrunnerdiff --git a/README.md b/README.mdindex 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-shAstryx 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/stylexnpm install -D @astryxdesign/cli# pnpm-pnpm add @astryxdesign/core @astryxdesign/theme-neutral+pnpm add @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylexpnpm add -D @astryxdesign/cli# yarn-yarn add @astryxdesign/core @astryxdesign/theme-neutral+yarn add @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylexyarn add -D @astryxdesign/cli```diff --git a/packages/cli/api/doctor/doctor.mjs b/packages/cli/api/doctor/doctor.mjsindex 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/nodimport {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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mdindex 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 peeInstall 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.