Use Astryx with shadcn

Astryx supports the shadcn Registry as a compatibility and distribution protocol. This does not make Astryx a shadcn-based library. The Astryx packages remain the implementation and the Astryx CLI remains the primary interface for discovery, composition, theming, validation, and upgrades.

A shadcn registry is static JSON that tells the shadcn CLI which package dependencies to install, which application-level files to copy, and which CSS imports to add. Read the protocol documentation at https://ui.shadcn.com/docs/registry.

This compatibility path is experimental. Use it to test incremental adoption in an existing shadcn-style application. Do not treat the registry URL or generated catalog as a stable support promise until Astryx announces it as supported.

Registry URLs are organized by item kind and derived from stable Astryx doc identity: component and hook name, block name plus exampleFor, and the existing page-template slug. displayName remains free to change without changing an install URL.

text
/r/components/button.json
/r/hooks/use-app-shell-mobile.json
/r/showcases/button/variants.json
/r/examples/button/icon.json
/r/blocks/filter-toolbar.json
/r/templates/dashboard.json

A doc may set registry.slug when the derived slug is not the intended public name. After publication, keep prior relative paths in registry.aliases. Generation compares every name and path with a reviewed route lock, so an accidental rename fails instead of silently breaking old commands.

A normal registry install never copies Astryx component implementation source. Deep source customization remains an explicit astryx swizzle <Name> action because copied implementation source leaves the package upgrade path.

Use the install command shown on a component, example, or template page. The shadcn CLI reads the item, installs the declared dependencies, writes the local composition or re-export, and adds the Astryx CSS imports to your configured stylesheet.

bash
npx shadcn@latest add <registry-origin>/components/button.json

bash
npx shadcn@latest add <registry-origin>/showcases/button/variants.json

bash
npx shadcn@latest add <registry-origin>/templates/dashboard.json

For a component entry, the command installs @astryxdesign/core and writes a small local file such as src/components/astryx/Button.ts that re-exports @astryxdesign/core/Button. Behavior, accessibility, styling, and fixes still come from the package.

ts
export * from '@astryxdesign/core/Button';

For an example, block, or page, the command writes editable TSX into your app. That TSX imports public Astryx package paths. It does not reach into package internals and it does not require a StyleX compiler in your app.

Use shadcn when you already use its registry workflow and know the exact item you want. Use the Astryx CLI when you need to discover the right component, compose a page from a natural-language request, inspect complete guidance, build a theme, validate an installation, or apply an upgrade codemod.

bash
astryx build "analytics dashboard with filters"
astryx component Button
astryx template dashboard
astryx doctor
astryx upgrade --apply

• Package upgrades update Astryx components, hooks, behavior, accessibility, and compiled styles.
• Copied examples, blocks, and pages are application code. They do not update automatically when the catalog changes.
• The experimental catalog excludes unpublished packages because an external package manager cannot install them.
• Your project needs a valid components.json and TypeScript configuration for the shadcn CLI to resolve target paths.
• The compatibility layer is additive. It does not require replacing existing shadcn components or migrating the whole application.