Consuming the registry

This guide covers installing components from the Mzizi registry, customising them after installation, and keeping them updated.

Rust first, where it exists

Mzizi’s components are being rebuilt in Rust as Mzizi Roots, and where a Rust implementation exists it is the one to prefer. A Dioxus project depends on the crates, which are on crates.io:

cargo add mzizi-roots        # tokens, primitives, brand components and the app shell

Or take one node crate, such as mzizi-ui or mzizi-brand. See Mzizi Roots for the features and the full list. The mzizi add installer in @nyuchi/mzizi-cli resolves a component by name: for a Rust project it names the crate and prints the cargo add to run, rather than copying .rs files. You can read any Rust component’s source too:

curl https://api.mzizi.dev/v1/rs/button

That route is a read surface, not an install path. Its crate field names the crate the component ships in, which differs by node: mzizi-ui for button, mzizi-brand for mzizi-alert-banner. The rest of this page covers the React build.

The Astro build

The registry is the single source of every component in every format: .tsx, .rs, .astro (and .mz as it lands). Where a component has an Astro implementation, it is a pure .astro file beside its .tsx and .rs, with no React, Svelte or Vue under it and no client JavaScript unless its contract allows one enhancement script. The Dashboard Standard (app-* and the primitives), the Discover Standard and its detail pattern (discover-*) and the marketing-site components (site-*) all have one.

npx @nyuchi/mzizi-cli add app-data-table --target astro

The installer infers --target astro in an Astro project, even one with React islands. It reads https://api.mzizi.dev/v1/astro/<name> and writes the component, every registry file it imports and any brand asset into src/components/mzizi/, then prints the npm dependencies to add. A component in the closure with no .astro is refused by name, never replaced by its .tsx. GET /v1/astro lists every name it serves. @bundu/ui ships the same .astro files as a package (@bundu/ui/app/*, @bundu/ui/discover/*): it is built from the registry at a pinned commit, and its CI fails if it drifts.

The React build

The React and TypeScript components are the React build. They keep working and install with the shadcn CLI, but they are deprioritised: not the lead, and not where new work goes.

Prerequisites

Before installing components, your project needs:

A components.json file — created by npx shadcn@latest init.
The cn() utility in lib/utils.ts.
Tailwind CSS with the Mzizi design tokens in your global stylesheet. See design tokens.

Installing

A single component

npx shadcn@latest add https://api.mzizi.dev/v1/ui/button

Several at once

npx shadcn@latest add \
  https://api.mzizi.dev/v1/ui/card \
  https://api.mzizi.dev/v1/ui/badge \
  https://api.mzizi.dev/v1/ui/dialog

Hooks and libraries

Hooks and library utilities install the same way — the item type in the manifest decides where the file lands.

npx shadcn@latest add https://api.mzizi.dev/v1/ui/use-toast
npx shadcn@latest add https://api.mzizi.dev/v1/ui/utils
npx shadcn@latest add https://api.mzizi.dev/v1/ui/circuit-breaker

Dependency resolution

Installing a component makes the CLI do two things automatically:

Install npm dependencies — packages such as radix-ui, class-variance-authority or recharts.
Install registry dependencies — other registry items the component needs. Installing dialog pulls in button.

You do not resolve dependencies by hand.

What you get

Components install as local files. A typical install creates:

components/
  ui/
    button.tsx    <- full source, in your repository, yours to edit

The file contains TypeScript with full type annotations, CVA variant definitions, Radix UI primitives where the component is interactive, cn() class composition, and data-slot attributes for stable styling hooks.

Customising after install

Because the file is yours, you edit it directly.

Adding a variant

// components/ui/button.tsx
const buttonVariants = cva("...", {
  variants: {
    variant: {
      default: "...",
      outline: "...",
      cobalt: "bg-[var(--color-cobalt)] text-white hover:bg-[var(--color-cobalt)]/90",
    },
  },
})

Extending props

interface ButtonProps
  extends React.ComponentProps<"button">,
    VariantProps<typeof buttonVariants> {
  loading?: boolean
}

Updating

To take the latest registry version of a component, run the same add command again:

npx shadcn@latest add https://api.mzizi.dev/v1/ui/button

This overwrites the local file. If you have customised it:

Commit your current state.
Run the update.
Read the diff and re-apply your changes.

There is no merge step and there is not meant to be one — the whole point of a file you own is that your version control, not the registry, arbitrates.

Using the API directly

You do not need the CLI, and you do not need to sign in. The JSON response carries the complete source in files[].content:

curl https://api.mzizi.dev/v1/ui/button
curl https://api.mzizi.dev/v1/ui

Practices worth keeping

Install from the registry rather than copying code out of documentation — the docs paraphrase, the API does not.
Keep cn(). Components depend on it from @/lib/utils.
Keep the token layer. Components reference CSS custom properties; without them they render with whatever your project’s fallbacks happen to be.
Test after updating. Check appearance and behaviour, not just that the build passes.
Track changes in version control so an update diff is legible.

Mzizi Roots

The registry

Registry architecture

Foundations

Patterns

Blocks

Charts

Content style

Consuming the registry

Rust first, where it exists

The Astro build

The React build

Prerequisites

Installing

A single component

Several at once

Hooks and libraries

Dependency resolution

What you get

Customising after install

Adding a variant

Extending props

Updating

Using the API directly

Practices worth keeping

​Rust first, where it exists

​The Astro build

​The React build

​Prerequisites

​Installing

​A single component

​Several at once

​Hooks and libraries

​Dependency resolution

​What you get

​Customising after install

​Adding a variant

​Extending props

​Updating

​Using the API directly

​Practices worth keeping

Rust first, where it exists

The Astro build

The React build

Prerequisites

Installing

A single component

Several at once

Hooks and libraries

Dependency resolution

What you get

Customising after install

Adding a variant

Extending props

Updating

Using the API directly

Practices worth keeping