Consuming the Registry

This guide covers how to install components from the Mukoko Registry, customize them after installation, and keep them updated.

Prerequisites

Before installing components, ensure your project has:

1. A components.json file (created by npx shadcn@latest init)
2. The cn() utility in lib/utils.ts
3. Tailwind CSS with the Five African Minerals tokens in globals.css

See the Installation guide for full setup instructions.

Installing components

Single component

npx shadcn@latest add https://registry.mukoko.com/api/v1/ui/button

Multiple components

npx shadcn@latest add \
  https://registry.mukoko.com/api/v1/ui/card \
  https://registry.mukoko.com/api/v1/ui/badge \
  https://registry.mukoko.com/api/v1/ui/dialog

Hooks

npx shadcn@latest add https://registry.mukoko.com/api/v1/ui/use-toast
npx shadcn@latest add https://registry.mukoko.com/api/v1/ui/use-mobile

Library utilities

npx shadcn@latest add https://registry.mukoko.com/api/v1/ui/utils
npx shadcn@latest add https://registry.mukoko.com/api/v1/ui/circuit-breaker

Dependency resolution

When you install a component, the CLI automatically:

1. Installs npm dependencies — packages like radix-ui, class-variance-authority, recharts
2. Installs registry dependencies — other Mukoko components the installed component needs (e.g., dialog pulls in button)

You do not need to manually resolve dependencies.

What you get

Components are installed as local files in your project. A typical install creates:

components/
  ui/
    button.tsx    ← Full source code, you own it

The file contains:

• TypeScript source with full type annotations
• CVA variant definitions
• Radix UI primitive usage for accessibility
• cn() class composition
• data-slot attributes for styling hooks

Customization after install

Since components are local files, you can modify them freely:

Adding a variant

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

Adjusting styles

// Change the default border radius
const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-xl ...", // Changed from rounded-md
  { ... }
)

Extending props

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

Updating components

To update a component to the latest registry version:

npx shadcn@latest add https://registry.mukoko.com/api/v1/ui/button

This overwrites the local file. If you have made customizations:

1. Commit your current changes to version control
2. Run the update
3. Review the diff and re-apply your customizations

Using the API directly

You can also fetch component data via the API without the CLI:

# Get component metadata and source
curl https://registry.mukoko.com/api/v1/ui/button
 
# List all components
curl https://registry.mukoko.com/api/v1/ui

The JSON response includes the full source code in the files[].content field, which you can copy manually if needed.

Best practices

1. Install from the registry — do not copy-paste component code from the documentation
2. Keep the utility function — components depend on cn() from @/lib/utils
3. Maintain the token system — components reference CSS custom properties; ensure your globals.css has all required tokens
4. Test after updates — verify visual consistency and behavior after updating components
5. Track changes — use version control to track modifications to installed components