Skip to content

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

TypeScript

docs: surface the React 19 peer requirement (#4645)

AK12dfaa728745
diff --git a/.changeset/react-version-docs-surface-requirement.md b/.changeset/react-version-docs-surface-requirement.md
new file mode 100644
index 0000000000..d6163bb874
--- /dev/null
+++ b/.changeset/react-version-docs-surface-requirement.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+'@astryxdesign/cli': patch
+---
+
+[docs] Surface the React 19 peer-dependency requirement everywhere a user would look for it (root README, core README, docsite hero, and the CLI getting-started guide), and add a sync test that keeps those surfaces naming the same React major as the core peer range.
+@AKnassa
diff --git a/README.md b/README.md
index aed28999f6..b3cd0bb68b 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
An open source design system that's fully customizable and built for how we build now: <br/> by people and the agents working alongside them.
-**Currently in Beta** · Built on [React](https://react.dev) and [StyleX](https://stylexjs.com)
+**Currently in Beta** · Built on [React 19+](https://react.dev) and [StyleX](https://stylexjs.com)
[![npm version](https://img.shields.io/npm/v/@astryxdesign/core?label=npm&color=cb3837&logo=npm)](https://www.npmjs.com/package/@astryxdesign/core)
[![license MIT](https://img.shields.io/npm/l/@astryxdesign/core?color=blue)](LICENSE)
@@ -37,6 +37,8 @@ It ships 150+ accessible components, brand-level theming, dark mode, ready-to-sh
## Getting Started
+Astryx requires **React 19** or later (`react` and `react-dom` are peer dependencies of `@astryxdesign/core`).
+
Install Astryx and a theme:
```bash
diff --git a/apps/docsite/src/app/(site)/page.tsx b/apps/docsite/src/app/(site)/page.tsx
index f7a1f69f1d..3368ecb1a0 100644
--- a/apps/docsite/src/app/(site)/page.tsx
+++ b/apps/docsite/src/app/(site)/page.tsx
@@ -232,7 +232,7 @@ function HeroContent({contentRef}: {contentRef: Ref<HTMLElement>}) {
target="_blank"
rel="noopener noreferrer"
hasUnderline>
- React
+ React 19+
</Link>{' '}
and{' '}
<Link
diff --git a/packages/cli/api/docs/react-version-sync.test.mjs b/packages/cli/api/docs/react-version-sync.test.mjs
new file mode 100644
index 0000000000..e6a9836ddb
--- /dev/null
+++ b/packages/cli/api/docs/react-version-sync.test.mjs
@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Keeps the documented React version requirement in sync with the peer
+ * dependency range declared by @astryxdesign/core (issue #4575: users must be
+ * able to discover the React 19 requirement without reading package.json).
+ *
+ * Runs against the real packages/core package.json, not mocks.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
+import {docs as gettingStarted} from '../../assets/docs/getting-started.doc.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+
+// Every place that names the supported React version. The docsite hero
+// (apps/docsite/src/app/(site)/page.tsx) is deliberately not asserted —
+// landing-page copy is a design call — but it names the version today, so
+// sweep it whenever these assertions send you updating the rest.
+const SURFACES =
+ 'update every surface that names the supported React version: README.md ' +
+ '(repo root), packages/core/README.md, ' +
+ 'packages/cli/assets/docs/getting-started.doc.mjs, and the docsite hero ' +
+ 'in apps/docsite/src/app/(site)/page.tsx';
+
+describe('documented React version matches the core peer dependency', () => {
+ const coreDir = findCoreDir();
+ const pkg = JSON.parse(
+ fs.readFileSync(path.join(coreDir, 'package.json'), 'utf-8'),
+ );
+ const reactRange = pkg.peerDependencies?.react;
+ if (typeof reactRange !== 'string') {
+ throw new Error(
+ '@astryxdesign/core no longer declares a react peer dependency; ' +
+ `${SURFACES}, then teach this test the new contract`,
+ );
+ }
+ const match = /\d+/.exec(reactRange);
+ if (!match) {
+ throw new Error(
+ `cannot read a major version from the react peer range "${reactRange}"; ` +
+ `${SURFACES}, then teach this test the new contract`,
+ );
+ }
+ const major = match[0];
+ // "React 19" but not "React 190"; also matches "React 19+".
+ const namesTheMajor = new RegExp(`React ${major}(?!\\d)`);
+
+ it('core declares matching react and react-dom peer ranges', () => {
+ expect(
+ pkg.peerDependencies['react-dom'],
+ `react and react-dom peer ranges diverged; if that is intentional, ${SURFACES}`,
+ ).toBe(reactRange);
+ });
+
+ it(`root README names React ${major}`, () => {
+ const readme = fs.readFileSync(path.join(REPO_ROOT, 'README.md'), 'utf-8');
+ expect(readme, SURFACES).toMatch(namesTheMajor);
+ });
+
+ it(`@astryxdesign/core README names React ${major}`, () => {
+ const readme = fs.readFileSync(path.join(coreDir, 'README.md'), 'utf-8');
+ expect(readme, SURFACES).toMatch(namesTheMajor);
+ });
+
+ it(`getting-started guide names React ${major} in prose`, () => {
+ const prose = gettingStarted.sections
+ .flatMap(section => section.content)
+ .filter(block => block.type === 'prose')
+ .map(block => block.text)
+ .join('\n');
+ expect(prose, SURFACES).toMatch(namesTheMajor);
+ });
+});
diff --git a/packages/cli/assets/docs/getting-started.doc.mjs b/packages/cli/assets/docs/getting-started.doc.mjs
index 90ed8ff05b..cd49239187 100644
--- a/packages/cli/assets/docs/getting-started.doc.mjs
+++ b/packages/cli/assets/docs/getting-started.doc.mjs
@@ -28,6 +28,10 @@ export const docs = {
{
title: 'Install',
content: [
+ {
+ type: 'prose',
+ text: 'Astryx requires React 19 or later: `react` and `react-dom` >= 19.0.0 are peer dependencies of `@astryxdesign/core`.',
+ },
{
type: 'prose',
text: 'Add the core package, a theme, and the CLI to your existing project.',
diff --git a/packages/core/README.md b/packages/core/README.md
index 7962582248..367aec9f33 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -75,6 +75,8 @@ astryx gap-report # report a missing capability
## Quick Start
+Astryx requires **React 19** or later (`react` and `react-dom` >= 19.0.0 are peer dependencies).
+
Install Astryx and a theme:
```bash