Use Astryx with shadcn

Install Astryx components, examples, blocks, and pages through the shadcn Registry workflow without replacing the Astryx package or CLI.

Overview

This guide is for existing shadcn users who want to add Astryx without replacing their current toolchain. Astryx supports the shadcn Registry as a compatibility and distribution protocol. The Astryx packages remain the implementation and the Astryx CLI remains the richer 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.

The registry is published as-is for existing shadcn users. Issues are welcome in the Astryx repository, with no response-time promise.

Naming and URL Stability

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.

Registry path families

text
/shadcn/components/button.json
/shadcn/hooks/use-app-shell-mobile.json
/shadcn/showcases/button/variants.json
/shadcn/examples/button/icon.json
/shadcn/blocks/filter-toolbar.json
/shadcn/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.

What Gets Installed

Item	What the CLI adds	Who owns updates
Component or hook	The published Astryx package plus a local public re-export	Astryx updates the implementation through the package
Showcase or example	Editable application-level composition source that imports Astryx packages	Your app owns its edits; the adjacent Astryx receipt enables safe upgrades
Block	A larger editable composition plus its package dependencies	Your app owns its edits; the adjacent Astryx receipt enables safe upgrades
Page	A complete editable page plus its package dependencies	Your app owns its edits; the adjacent Astryx receipt enables safe upgrades

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.

Install with shadcn

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.

Install the Button package entry

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

Install the editable Button showcase

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

Install the complete dashboard page

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

What the Command Changes

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.

Generated public re-export

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

For an example, block, or page, the command writes editable TSX plus a small adjacent .astryx receipt. The TSX imports public Astryx package paths. The receipt stores the exact installed base so a later upgrade can preserve your edits; it is not application code and should stay committed with the copied file.

Use the Astryx CLI for the Richer Path

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.

Astryx discovery and maintenance

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

Upgrade Model and Limits

Package upgrades update Astryx components, hooks, behavior, accessibility, and compiled styles.
A normal astryx upgrade also checks copied-composition receipts. Use astryx upgrade --registry to preview only those files; add --apply to write safe updates.
Registry source must match the installed Astryx release. The command refuses to copy source from a newer or older release.
An unchanged copied file updates automatically. Non-overlapping edits are three-way merged against the installed base.
A conflicting edit leaves your file untouched and writes a separate .astryx-conflict file for review.
A deleted or moved copied file is reported but never recreated or overwritten.
The registry 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.