Skip to content

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

TypeScript

docsite: pass DocsShell a small nav model instead of the full registries (#9907)

Cindy Zhangd3ec2efe3935
diff --git a/apps/docsite/src/__tests__/docs-nav.test.ts b/apps/docsite/src/__tests__/docs-nav.test.ts
new file mode 100644
index 0000000000..71e05f41c9
--- /dev/null
+++ b/apps/docsite/src/__tests__/docs-nav.test.ts
@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Docs nav model: the (docs) layout gives DocsShell a small projection of
+ * the registries. DocsShell is a client component, so React serializes its
+ * props into every docs page, and the modules it imports ship to the browser.
+ */
+
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {describe, it, expect} from 'vitest';
+import {packages} from '../generated/packageRegistry';
+import {docTopics} from '../generated/docsRegistry';
+import {flattenComponentSidebarEntries} from '../components/componentSidebarData';
+import {getDocsNav, type DocsNavItem} from '../components/docsNav';
+
+function flattenNavEntries(items: DocsNavItem[]) {
+ return items.flatMap(item => (item.type === 'entry' ? [item] : item.entries));
+}
+
+describe('docs nav model', () => {
+ const nav = getDocsNav();
+
+ it('keeps every package and doc topic, in registry order', () => {
+ expect(nav.packages).toEqual(
+ packages.map(({name, displayName, canaryOnly}) => ({
+ name,
+ displayName,
+ canaryOnly,
+ })),
+ );
+ expect(nav.docTopics).toEqual(
+ docTopics.map(({topic, title, category}) => ({topic, title, category})),
+ );
+ });
+
+ it('keeps every component sidebar entry, in sidebar order', () => {
+ const navEntries = [
+ ...flattenNavEntries(nav.componentItems),
+ ...nav.utilities,
+ ...nav.canaryCategories.flatMap(category => [
+ ...flattenNavEntries(category.componentItems),
+ ...category.utilities,
+ ]),
+ ];
+ expect(navEntries).toEqual(
+ flattenComponentSidebarEntries().map(
+ ({type, name, displayName, href, packageName}) => ({
+ type,
+ name,
+ displayName,
+ href,
+ packageName,
+ }),
+ ),
+ );
+ });
+
+ it('stays small enough to inline into every docs page', () => {
+ // The full registries are megabytes. The nav model is a few tens of KB.
+ expect(JSON.stringify(nav).length).toBeLessThan(100_000);
+ });
+
+ it('keeps registry modules out of the DocsShell client bundle', () => {
+ const source = readFileSync(
+ join(__dirname, '../components/DocsShell.tsx'),
+ 'utf8',
+ );
+ const dataImports = [
+ ...source.matchAll(
+ /^import\s+(type\s+)?[^;]*?from\s+'(\.\.\/generated\/[^']+|\.\/componentSidebarData|\.\/docsNav)';/gm,
+ ),
+ ];
+ expect(dataImports.length).toBeGreaterThan(0);
+ for (const [statement, typeOnly] of dataImports) {
+ expect(typeOnly, statement).toBeTruthy();
+ }
+ });
+});
diff --git a/apps/docsite/src/app/(docs)/layout.tsx b/apps/docsite/src/app/(docs)/layout.tsx
index d3877581c8..915fd1b57c 100644
--- a/apps/docsite/src/app/(docs)/layout.tsx
+++ b/apps/docsite/src/app/(docs)/layout.tsx
@@ -3,8 +3,7 @@
import {DocsShell} from '../../components/DocsShell';
import {SiteFooter} from '../../components/SiteFooter';
import {getCopyrightYear} from '../../lib/copyrightYear';
-import {packages} from '../../generated/packageRegistry';
-import {docTopics} from '../../generated/docsRegistry';
+import {getDocsNav} from '../../components/docsNav';
export default async function DocsLayout({
children,
@@ -14,7 +13,7 @@ export default async function DocsLayout({
const year = await getCopyrightYear();
return (
- <DocsShell packages={packages} docTopics={docTopics}>
+ <DocsShell nav={getDocsNav()}>
{children}
<SiteFooter year={year} />
</DocsShell>
diff --git a/apps/docsite/src/components/DocsShell.tsx b/apps/docsite/src/components/DocsShell.tsx
index aaa14f21da..09ffcade59 100644
--- a/apps/docsite/src/components/DocsShell.tsx
+++ b/apps/docsite/src/components/DocsShell.tsx
@@ -4,7 +4,7 @@
/**
* @file DocsShell.tsx
- * @input Route metadata, component registry, and the rendered AppShell header
+ * @input Route metadata, the server-built docs nav model, and the AppShell header
* @output Docs navigation with a stable sidebar offset before hydration
* @position Docsite-only shell
*/
@@ -20,18 +20,17 @@ import {Icon} from '@astryxdesign/core/Icon';
import {SharedTopNav} from './SharedTopNav';
import {HeaderHeightSeed} from './HeaderHeightSeed';
import {DocsBanner} from './InternalDocsPrompt';
-import type {PackageMeta} from '../generated/packageRegistry';
-import type {DocTopic} from '../generated/docsRegistry';
-import {
- getComponentSidebarData,
- type ComponentSidebarEntry,
- type ComponentSidebarItem,
-} from './componentSidebarData';
+import type {
+ DocsNav,
+ DocsNavEntry,
+ DocsNavItem,
+ DocsNavPackage,
+ DocsNavTopic,
+} from './docsNav';
interface DocsShellProps {
children: React.ReactNode;
- packages: PackageMeta[];
- docTopics: DocTopic[];
+ nav: DocsNav;
}
const styles = stylex.create({
@@ -53,7 +52,7 @@ function CanaryCategoryMarker() {
}
/** Foundations: tokens first, then alphabetical */
-const foundationsSort = (a: DocTopic, b: DocTopic) => {
+const foundationsSort = (a: DocsNavTopic, b: DocsNavTopic) => {
if (a.topic === 'tokens') {
return -1;
}
@@ -65,18 +64,18 @@ const foundationsSort = (a: DocTopic, b: DocTopic) => {
// ── Shell ──────────────────────────────────────────────────────────────
-export function DocsShell({children, packages, docTopics}: DocsShellProps) {
+export function DocsShell({children, nav}: DocsShellProps) {
const pathname = usePathname();
const [componentQuery, setComponentQuery] = useState('');
- const {componentItems, utilities, canaryCategories} =
- getComponentSidebarData();
+ const {packages, docTopics, componentItems, utilities, canaryCategories} =
+ nav;
const q = componentQuery.trim().toLowerCase();
// When searching, flatten every readiness category to individual entries so
// results are all at the same level with no nesting.
- const flatSearchResults = useMemo<ComponentSidebarEntry[]>(() => {
+ const flatSearchResults = useMemo<DocsNavEntry[]>(() => {
if (!q) {
return [];
}
@@ -103,7 +102,7 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {
}, [canaryCategories, utilities, q]);
// Classify packages
- const isTheme = (p: PackageMeta) => p.name.includes('theme-');
+ const isTheme = (p: DocsNavPackage) => p.name.includes('theme-');
const libraryPackages = packages.filter(p => !isTheme(p) && !p.canaryOnly);
const canaryPackages = packages.filter(p => !isTheme(p) && p.canaryOnly);
@@ -134,7 +133,7 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {
/>
);
- const renderComponentItems = (items: ComponentSidebarItem[]) =>
+ const renderComponentItems = (items: DocsNavItem[]) =>
items.map(item =>
item.type === 'entry' ? (
<SideNavItem
diff --git a/apps/docsite/src/components/docsNav.ts b/apps/docsite/src/components/docsNav.ts
new file mode 100644
index 0000000000..56923de3c9
--- /dev/null
+++ b/apps/docsite/src/components/docsNav.ts
@@ -0,0 +1,109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file docsNav.ts
+ * @input Generated package and docs registries, component sidebar data
+ * @output The docs sidebar model with only the fields DocsShell reads
+ * @position Server-side projection that the (docs) layout passes to DocsShell
+ *
+ * SYNC: When DocsShell reads another registry field, add it here.
+ */
+
+import {packages, type PackageMeta} from '../generated/packageRegistry';
+import {docTopics, type DocTopic} from '../generated/docsRegistry';
+import {
+ getComponentSidebarData,
+ type ComponentSidebarEntry,
+ type ComponentSidebarGroup,
+ type ComponentSidebarItem,
+} from './componentSidebarData';
+
+export type DocsNavPackage = Pick<
+ PackageMeta,
+ 'name' | 'displayName' | 'canaryOnly'
+>;
+
+export type DocsNavTopic = Pick<DocTopic, 'topic' | 'title' | 'category'>;
+
+export type DocsNavEntry = Pick<
+ ComponentSidebarEntry,
+ 'type' | 'name' | 'displayName' | 'href' | 'packageName'
+>;
+
+export interface DocsNavGroup extends Pick<
+ ComponentSidebarGroup,
+ 'type' | 'label' | 'displayName' | 'packageName'
+> {
+ entries: DocsNavEntry[];
+}
+
+export type DocsNavItem = DocsNavEntry | DocsNavGroup;
+
+export interface DocsNavCanaryCategory {
+ packageName: string;
+ displayName: string;
+ componentItems: DocsNavItem[];
+ utilities: DocsNavEntry[];
+}
+
+export interface DocsNav {
+ packages: DocsNavPackage[];
+ docTopics: DocsNavTopic[];
+ componentItems: DocsNavItem[];
+ utilities: DocsNavEntry[];
+ canaryCategories: DocsNavCanaryCategory[];
+}
+
+function toNavEntry({
+ type,
+ name,
+ displayName,
+ href,
+ packageName,
+}: ComponentSidebarEntry): DocsNavEntry {
+ return {type, name, displayName, href, packageName};
+}
+
+function toNavItem(item: ComponentSidebarItem): DocsNavItem {
+ if (item.type === 'entry') {
+ return toNavEntry(item);
+ }
+ const {type, label, displayName, packageName, entries} = item;
+ return {
+ type,
+ label,
+ displayName,
+ packageName,
+ entries: entries.map(toNavEntry),
+ };
+}
+
+/**
+ * React serializes the props of a client component into every page that
+ * renders it. The registries hold full readmes, changelogs, and doc sections,
+ * so the shell gets this small projection and not the registries.
+ */
+export function getDocsNav(): DocsNav {
+ const {componentItems, utilities, canaryCategories} =
+ getComponentSidebarData();
+ return {
+ packages: packages.map(({name, displayName, canaryOnly}) => ({
+ name,
+ displayName,
+ canaryOnly,
+ })),
+ docTopics: docTopics.map(({topic, title, category}) => ({
+ topic,
+ title,
+ category,
+ })),
+ componentItems: componentItems.map(toNavItem),
+ utilities: utilities.map(toNavEntry),
+ canaryCategories: canaryCategories.map(category => ({
+ packageName: category.packageName,
+ displayName: category.displayName,
+ componentItems: category.componentItems.map(toNavItem),
+ utilities: category.utilities.map(toNavEntry),
+ })),
+ };
+}