Skip to content

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

TypeScript

feat(docsite): generate example block registry with dynamic imports (#1996)

Cindy Zhangb8c4e0bab1cb
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 119eaf7888..f40eb92a92 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -746,6 +746,81 @@ ${importLines}
// ── Main
+function generateExampleRegistry() {
+ console.log('Generating example registry...');
+
+ const BLOCKS_DIR = path.join(CLI_ROOT, 'templates', 'blocks');
+ const EXAMPLES_OUT = path.join(OUT_DIR, 'examples');
+
+ if (fs.existsSync(EXAMPLES_OUT)) {
+ fs.rmSync(EXAMPLES_OUT, {recursive: true});
+ }
+ fs.mkdirSync(EXAMPLES_OUT, {recursive: true});
+
+ const docFiles = findDocFilesRecursive(BLOCKS_DIR);
+ const entries = [];
+
+ for (const docPath of docFiles) {
+ const content = fs.readFileSync(docPath, 'utf-8');
+ // Skip showcases — they have their own registry
+ if (/isShowcase:\s*true/.test(content)) continue;
+
+ const efMatch = content.match(/exampleFor:\s*['"]([^'"]+)['"]/);
+ if (!efMatch) continue;
+
+ const exampleFor = efMatch[1];
+ const basename = path.basename(docPath, '.doc.mjs');
+ const tsxSrc = path.join(path.dirname(docPath), basename + '.tsx');
+ if (!fs.existsSync(tsxSrc)) continue;
+
+ // Read name and description from doc meta
+ const nameMatch = content.match(/name:\s*['"]([^'"]+)['"]/);
+ const descMatch = content.match(/description:\s*\n?\s*['"`]([^'"`]{0,200})['"`]/);
+
+ fs.copyFileSync(tsxSrc, path.join(EXAMPLES_OUT, `${basename}.tsx`));
+
+ entries.push({
+ exampleFor,
+ basename,
+ name: nameMatch?.[1] || basename,
+ description: descMatch?.[1] || '',
+ });
+ }
+
+ // Group by component
+ const grouped = {};
+ for (const e of entries) {
+ if (!grouped[e.exampleFor]) grouped[e.exampleFor] = [];
+ grouped[e.exampleFor].push(e);
+ }
+
+ // Generate registry: component name → array of example metadata + loaders
+ const componentLines = Object.entries(grouped).map(([comp, examples]) => {
+ const exampleLines = examples.map(
+ e => ` {name: ${JSON.stringify(e.name)}, description: ${JSON.stringify(e.description)}, load: () => import('./examples/${e.basename}')},`
+ ).join('\n');
+ return ` '${comp}': [\n${exampleLines}\n ],`;
+ }).join('\n');
+
+ const registryContent = `// Auto-generated by scripts/generate-data.mjs — do not edit
+import type {ComponentType} from 'react';
+
+export interface ExampleEntry {
+ name: string;
+ description: string;
+ load: () => Promise<{default: ComponentType}>;
+}
+
+export const exampleRegistry: Record<string, ExampleEntry[]> = {
+${componentLines}
+};
+`;
+
+ writeRegistry('exampleRegistry.ts', registryContent);
+ console.log(` copied ${entries.length} example blocks for ${Object.keys(grouped).length} components`);
+ return entries.length;
+}
+
async function main() {
console.log('Generating docsite data...\n');
@@ -756,11 +831,12 @@ async function main() {
const {templateCount} = await generateTemplateRegistry();
const {docsCount} = await generateDocsRegistry();
const showcaseCopied = generateShowcaseRegistry();
+ const examplesCopied = generateExampleRegistry();
console.log(`\nSummary:`);
console.log(` ${packages.length} packages`);
console.log(` ${componentCount} components`);
- console.log(` ${blockCount} blocks (${showcaseCount} showcases, ${showcaseCopied} copied)`);
+ console.log(` ${blockCount} blocks (${showcaseCopied} showcases, ${examplesCopied} examples)`);
console.log(` ${templateCount} templates`);
console.log(` ${docsCount} doc topics`);
console.log(` ${themeCount} themes`);
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index 0feff7a78f..194af70b8e 100644
--- a/apps/docsite/src/__tests__/data-extraction.test.ts
+++ b/apps/docsite/src/__tests__/data-extraction.test.ts
@@ -13,6 +13,7 @@ import {blocks, blockCount, showcaseCount} from '../generated/blockRegistry';
import {templates, templateCount} from '../generated/templateRegistry';
import {docTopics, docsCount} from '../generated/docsRegistry';
import {showcaseRegistry} from '../generated/showcaseRegistry';
+import {exampleRegistry} from '../generated/exampleRegistry';
// ── Package Registry ───────────────────────────────────────────────────
@@ -535,3 +536,58 @@ describe('showcaseRegistry', () => {
expect(keys.length).toBeLessThanOrEqual(files.length);
});
});
+
+// ── Example Registry ───────────────────────────────────────────────────
+
+describe('exampleRegistry', () => {
+ it('has examples for many components', () => {
+ const keys = Object.keys(exampleRegistry);
+ expect(keys.length).toBeGreaterThan(50);
+ });
+
+ it('every entry is an array of example objects', () => {
+ for (const [, examples] of Object.entries(exampleRegistry)) {
+ expect(Array.isArray(examples)).toBe(true);
+ expect(examples.length).toBeGreaterThan(0);
+ for (const ex of examples) {
+ expect(typeof ex.name).toBe('string');
+ expect(ex.name.length).toBeGreaterThan(0);
+ expect(typeof ex.description).toBe('string');
+ expect(typeof ex.load).toBe('function');
+ }
+ }
+ });
+
+ it('has examples for known components', () => {
+ expect(exampleRegistry['Button']).toBeDefined();
+ expect(exampleRegistry['Table']).toBeDefined();
+ expect(exampleRegistry['Dialog']).toBeDefined();
+ });
+
+ it('Button has multiple examples', () => {
+ const buttonExamples = exampleRegistry['Button'];
+ expect(buttonExamples.length).toBeGreaterThanOrEqual(3);
+ });
+
+ it('example files exist on disk', () => {
+ const examplesDir = new URL('../generated/examples', import.meta.url);
+ const files = fs.readdirSync(examplesDir);
+ expect(files.length).toBeGreaterThan(200);
+ expect(files.every(f => f.endsWith('.tsx'))).toBe(true);
+ });
+
+ it('does not include showcases', () => {
+ // Every example in the registry should NOT be a showcase
+ // (showcases have their own registry)
+ const allExampleNames = Object.values(exampleRegistry)
+ .flat()
+ .map(e => e.name);
+ // Showcase names typically don't have a dash separator
+ // but more importantly, the generator filters isShowcase: true
+ // Just verify count makes sense: examples + showcases ≈ total blocks
+ const showcaseCount = Object.keys(showcaseRegistry).length;
+ const exampleCount = Object.values(exampleRegistry).flat().length;
+ expect(exampleCount + showcaseCount).toBeLessThanOrEqual(468);
+ expect(exampleCount).toBeGreaterThan(showcaseCount);
+ });
+});