zedkit and shadcn/ui
What the UI kit wraps, what it adds beyond copying components, when to stay on plain shadcn/ui, and how registry install relates to npm.
Hand-written guide. Claims below point at files you can open in the public repo.
Who this is for
You already use shadcn/ui or Radix primitives and wonder whether
@zedtech/zedkit-ui replaces them, duplicates them, or sits beside them.
What zedkit wraps (verify in source)
The UI package lists runtime dependencies in
packages/ui/package.json.
Today that includes, among others:
| Library | Role in zedkit | Catalog example |
|---|---|---|
Radix UI (@radix-ui/react-*) | Accessible primitives for dialogs, menus, tabs, etc. | Open modal dialogs (Derived from: shadcn/ui (dialog) in CATALOG.md) |
vaul | Drawer motion and behavior | Slide in a drawer panel |
react-hook-form + zod + @hookform/resolvers | Form state and schema validation | Build validated forms |
@tanstack/react-table | Data table sorting, filtering, pagination | Show a sortable, filterable, paginated data table |
sonner | Toasts | Show toast notifications |
tailwind-merge, class-variance-authority, clsx | Class composition and variants | Merge class names without conflicts |
Each catalog need’s Wraps line names the direct npm dependency; many bricks also carry Derived from: shadcn/ui (...) when the component file follows the shadcn layout.
What zedkit adds
- Composed admin patterns — layout shell, data table, multi-step flows, and similar needs are first-class catalog entries, not only atomic primitives.
- Shared theme tokens —
packages/ui/src/styles.cssand Theme an admin app document dark/light setup for Tailwind v4. - Generated docs — catalog → MDX pages, live previews, and (for registry bricks) install
JSON from
registry.json(see COMPONENT-PAGE.md). - Thin wrappers elsewhere — non-UI packages follow the repo golden rule: one stable import surface over a mature library.
npm install vs registry (shadcn add)
| Path | When | What you get |
|---|---|---|
pnpm add @zedtech/zedkit-ui | You want the published package API and CSS entry | Imports from @zedtech/zedkit-ui; version pinned on each doc page’s Install tabs |
npx shadcn@latest add https://zedkit.app/r/<brick>.json | You want source files in your repo like upstream shadcn | Files from registry/generated/ui/ with imports rewritten at build time (pnpm registry:build — apps/docs/AGENTS.md) |
Registry bricks are listed in registry.json; only published JSON URLs under /r/ are
documented on component pages. If a brick is not in the registry yet, use npm imports until
it ships.
When to prefer plain shadcn/ui
Stay on upstream shadcn/ui (or your own forks) when:
- You need full control over every component file and do not want a versioned package boundary.
- Your design system diverges from the kit tokens and you will not adopt
styles.css. - You only need one primitive and none of the composed catalog needs apply.
Reach for zedkit when several catalog needs match your admin app and you want docs, previews, and install commands to stay aligned with the npm release.
Scenario
You start a Next.js admin app. You install @zedtech/zedkit-ui, follow the theme doc, and
copy the Button usage from Trigger actions with buttons.
Later you add a drawer via npx shadcn add using the registry URL on that component page so
the file lands in your tree with the same import paths the docs show.
Troubleshooting
| Symptom | What to check |
|---|---|
shadcn add 404 | Brick not published yet — check registry.json and the component page’s Install section. |
| Styles look like unstyled HTML | Theme doc not applied (Tailwind v4 + kit CSS). |
| Types differ from shadcn docs | You imported @zedtech/zedkit-ui; props match the generated Props table on the catalog page, not third-party snippets. |
| Want only Radix, no kit | Use Radix directly; zedkit does not block that — it is an optional layer. |
Next steps
- Getting started — prerequisites and first commands
- Golden rule — wrapping other libraries in backend packages
- Documentation index — pick a need by folder