Skip to content

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

TypeScript

fix(docsite): serve each shadcn registry item at its name in the registry root (#7882)

Joey2468b8aad777
diff --git a/apps/docsite/scripts/generate-shadcn-registry.mjs b/apps/docsite/scripts/generate-shadcn-registry.mjs
index 4b670671d8..ae4de07cd2 100644
--- a/apps/docsite/scripts/generate-shadcn-registry.mjs
+++ b/apps/docsite/scripts/generate-shadcn-registry.mjs
@@ -36,6 +36,7 @@ import {
blockRegistryIdentity,
componentRegistryIdentity,
pageRegistryIdentity,
+ registryNameForPath,
} from '../src/lib/shadcnRegistry.mjs';
const REGISTRY_SCHEMA = 'https://ui.shadcn.com/schema/registry.json';
@@ -517,10 +518,30 @@ function assertUniqueItemNames(items) {
}
}
+/**
+ * Every file an item is written to, without `.json`: its organized path and
+ * aliases, plus the root name route standard clients derive from an index
+ * name (`shadcn search`, `@namespace/<name>`). An alias path also keeps the
+ * name it stood for, so a renamed item still answers at its old name.
+ */
+export function itemRoutes(item) {
+ if (registryNameForPath(item.astryx.path) !== item.name) {
+ throw new Error(
+ `${item.name} does not match the name of its path ${item.astryx.path}`,
+ );
+ }
+ const organized = [item.astryx.path, ...item.astryx.aliases];
+ return [...organized, ...organized.map(registryNameForPath)];
+}
+
function assertUniqueItemPaths(items) {
+ // Names are kind-prefixed slugs with no slash and every organized path
+ // starts with a kind folder, so a name route can meet neither a path route
+ // nor the `registry.json` index; checking every route in one set still
+ // fails generation if any two items would write the same file.
const paths = new Map();
for (const item of items) {
- for (const itemPath of [item.astryx.path, ...item.astryx.aliases]) {
+ for (const itemPath of itemRoutes(item)) {
const existing = paths.get(itemPath);
if (existing) {
throw new Error(
@@ -748,7 +769,7 @@ export function generateShadcnRegistry({
fs.mkdirSync(outDir, {recursive: true});
writeJson(path.join(outDir, 'registry.json'), result.registry);
for (const item of result.items) {
- for (const itemPath of [item.astryx.path, ...item.astryx.aliases]) {
+ for (const itemPath of itemRoutes(item)) {
writeJson(path.join(outDir, `${itemPath}.json`), item);
}
}
diff --git a/apps/docsite/src/lib/shadcnRegistry.d.mts b/apps/docsite/src/lib/shadcnRegistry.d.mts
index 58c581f4da..c6b9db5074 100644
--- a/apps/docsite/src/lib/shadcnRegistry.d.mts
+++ b/apps/docsite/src/lib/shadcnRegistry.d.mts
@@ -63,3 +63,4 @@ export function shadcnInstallCommand(
itemPath: string,
registryOrigin?: string,
): string;
+export function registryNameForPath(registryPath: string): string;
diff --git a/apps/docsite/src/lib/shadcnRegistry.mjs b/apps/docsite/src/lib/shadcnRegistry.mjs
index 5fcfd6671d..d4b1846a6a 100644
--- a/apps/docsite/src/lib/shadcnRegistry.mjs
+++ b/apps/docsite/src/lib/shadcnRegistry.mjs
@@ -216,6 +216,32 @@ export function pageRegistryIdentity(templateSlug, registry = null) {
};
}
+const NAME_PREFIX_BY_ROOT = {
+ components: 'component',
+ hooks: 'hook',
+ showcases: 'showcase',
+ examples: 'example',
+ blocks: 'block',
+ templates: 'template',
+};
+
+/**
+ * The item name an organized path stands for: the singular kind root followed
+ * by the remaining path segments, joined with hyphens. Every item's name equals
+ * the name of its canonical path, and an alias path names the item it used to
+ * be, so a renamed item keeps answering at its old `<name>.json` too.
+ */
+export function registryNameForPath(registryPath) {
+ const [root, ...rest] = registryPath.split('/');
+ const prefix = NAME_PREFIX_BY_ROOT[root];
+ if (prefix == null || rest.length === 0) {
+ throw new Error(
+ `registry path ${JSON.stringify(registryPath)} does not start with a kind folder`,
+ );
+ }
+ return `${prefix}-${rest.join('-')}`;
+}
+
export function shadcnComponentItemName(
packageName,
componentName,
diff --git a/docs/specs/AST-026/spec.md b/docs/specs/AST-026/spec.md
index 2e544cc14c..115412b499 100644
--- a/docs/specs/AST-026/spec.md
+++ b/docs/specs/AST-026/spec.md
@@ -202,6 +202,11 @@ Allow a doc to override its leaf with `registry.slug` and retain old relative
paths with `registry.aliases`. Check all names and paths against a reviewed lock
so a rename cannot silently break existing install commands.
+Every item is also served at `<name>.json` in the registry root with its
+canonical bytes. Standard clients build that address from the index name, in
+search results and in `@namespace/<name>` installs. Each alias path also keeps
+the name it stood for, so a renamed item still installs by its old name.
+
### DEC-5 — Use `/shadcn`, exact releases, and canary previews
**Reference:** `spec:AST-026/DEC-5`
diff --git a/internal/shadcn-registry/generate-shadcn-registry.test.mjs b/internal/shadcn-registry/generate-shadcn-registry.test.mjs
index 5c6bec6eba..7a67b12b70 100644
--- a/internal/shadcn-registry/generate-shadcn-registry.test.mjs
+++ b/internal/shadcn-registry/generate-shadcn-registry.test.mjs
@@ -42,6 +42,7 @@ import {
blockRegistryIdentity,
componentRegistryIdentity,
pageRegistryIdentity,
+ registryNameForPath,
resolveShadcnRegistryOrigin,
shadcnInstallCommand,
} from '../../apps/docsite/src/lib/shadcnRegistry.mjs';
@@ -409,11 +410,71 @@ describe('buildShadcnRegistry', () => {
);
expect(result.routes).toContain('showcases/button/variants');
expect(result.routes).toContain('blocks/filter-toolbar');
+
+ // Every item is also served at `<name>.json` in the root, the address
+ // standard clients derive from the index, with the canonical bytes.
+ for (const [name, canonical] of [
+ ['component-button', 'components/button'],
+ ['showcase-button-button-styles', 'showcases/button/button-styles'],
+ ['block-filter-toolbar', 'blocks/filter-toolbar'],
+ ['template-dashboard', 'templates/dashboard'],
+ ]) {
+ expect(readFileSync(path.join(outDir, `${name}.json`), 'utf8')).toBe(
+ readFileSync(path.join(outDir, `${canonical}.json`), 'utf8'),
+ );
+ }
+ // The alias keeps the name it stood for, so a renamed item still
+ // installs as `@namespace/<old-name>`.
+ expect(
+ readFileSync(
+ path.join(outDir, 'showcase-button-variants.json'),
+ 'utf8',
+ ),
+ ).toBe(
+ readFileSync(
+ path.join(outDir, 'showcases', 'button', 'button-styles.json'),
+ 'utf8',
+ ),
+ );
+ } finally {
+ rmSync(outDir, {recursive: true, force: true});
+ }
+ });
+
+ it('fails generation when two items would claim the same route', () => {
+ const outDir = mkdtempSync(path.join(tmpdir(), 'astryx-shadcn-clash-'));
+ try {
+ const input = fixture();
+ input.blocks[0].registry = {slug: 'button-styles'};
+ input.blocks.push({
+ ...input.blocks[0],
+ dirName: 'ButtonStylesCopy',
+ name: 'Button Styles Copy',
+ displayName: 'Button Styles Copy',
+ });
+ expect(() =>
+ generateShadcnRegistry({...input, outDir, cliRoot: outDir}),
+ ).toThrow(/Duplicate shadcn registry item name/);
} finally {
rmSync(outDir, {recursive: true, force: true});
}
});
+ it('maps every organized path to the item name it stands for', () => {
+ expect(registryNameForPath('components/button')).toBe('component-button');
+ expect(registryNameForPath('components/lab/line-clamp')).toBe(
+ 'component-lab-line-clamp',
+ );
+ expect(registryNameForPath('examples/button/icon')).toBe(
+ 'example-button-icon',
+ );
+ expect(registryNameForPath('templates/dashboard')).toBe(
+ 'template-dashboard',
+ );
+ // No route can be the index: every name starts with a kind prefix.
+ expect(() => registryNameForPath('registry')).toThrow(/kind folder/);
+ });
+
it('generates exact-version compatibility output for production', () => {
const root = mkdtempSync(path.join(tmpdir(), 'astryx-shadcn-production-'));
const outDir = path.join(root, 'shadcn');
diff --git a/internal/shadcn-registry/verify-full-catalog.mjs b/internal/shadcn-registry/verify-full-catalog.mjs
index 9c458202a6..303ad11ecc 100644
--- a/internal/shadcn-registry/verify-full-catalog.mjs
+++ b/internal/shadcn-registry/verify-full-catalog.mjs
@@ -33,6 +33,7 @@ import {
registryContentHash,
} from '../../packages/cli/authoring/shadcn/receipt.mjs';
import {expandWorkspaceDirs} from '../../scripts/lib/workspace-globs.mjs';
+import {registryNameForPath} from '../../apps/docsite/src/lib/shadcnRegistry.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = path.resolve(__dirname, '../..');
@@ -270,6 +271,26 @@ function loadCatalog() {
fail(`${registryPath}.json does not match its registry.json identity`);
}
+ // Search results and `@namespace/<name>` resolve `<name>.json` in the
+ // registry root, and an alias keeps the old name it stood for; each must
+ // serve the canonical item's exact bytes.
+ const organized = [registryPath, ...(item.astryx?.aliases ?? [])];
+ for (const nameRoute of organized.map(registryNameForPath)) {
+ const nameFile = resolveInside(
+ REGISTRY_DIR,
+ `${nameRoute}.json`,
+ `${name} name route`,
+ );
+ if (!fs.existsSync(nameFile)) {
+ fail(`${name} is missing its name route ${nameRoute}.json`);
+ }
+ if (fs.readFileSync(nameFile, 'utf8') !== canonicalBytes) {
+ fail(
+ `name route ${nameRoute}.json drifted from canonical item ${name}`,
+ );
+ }
+ }
+
for (const route of [registryPath, ...(item.astryx?.aliases ?? [])]) {
const prior = routes.get(route);
if (prior != null) {