> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mzizi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Consuming the registry

> How to install Mzizi components into your application, customise them afterwards, and take updates without losing your changes.

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](/roots/overview), and where a
Rust implementation exists it is the one to prefer. A Dioxus project depends on the crates,
which are on crates.io:

```bash theme={null}
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](/roots/overview#install) for the features and the full list. The
[`mzizi add` installer](/toolchain/cli#mzizi-add-the-registry-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:

```bash theme={null}
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](/patterns/discover-standard) and its
[detail pattern](/patterns/discover-detail) (`discover-*`) and the marketing-site components
(`site-*`) all have one.

```bash theme={null}
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:

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

## Installing

### A single component

```bash theme={null}
npx shadcn@latest add https://api.mzizi.dev/v1/ui/button
```

### Several at once

```bash theme={null}
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.

```bash theme={null}
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:

1. **Install npm dependencies** — packages such as `radix-ui`, `class-variance-authority` or
   `recharts`.
2. **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

```tsx theme={null}
// 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

```tsx theme={null}
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:

```bash theme={null}
npx shadcn@latest add https://api.mzizi.dev/v1/ui/button
```

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

1. Commit your current state.
2. Run the update.
3. 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`:

```bash theme={null}
curl https://api.mzizi.dev/v1/ui/button
curl https://api.mzizi.dev/v1/ui
```

## Practices worth keeping

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.