How to Use

This guide walks you through adding a new component to Homokozoo. By the end your component will have its own docs page and be installable from the registry.

Use the existing Example component as a reference:

Component Source

Create a new file under src/components/. For a component called foo:

src/components/foo.tsx

Follow this structure:

• Define a typed props interface (e.g. FooProps)
• Export a named component function (e.g. export function Foo(...))
• Add 'use client'; only if the component uses browser APIs, Canvas, or client-only hooks

'use client';

import type { HTMLAttributes } from 'react';

export interface FooProps extends HTMLAttributes<HTMLDivElement> {
  label?: string;
}

export function Foo({ label = 'Hello', ...props }: FooProps) {
  return <div {...props}>{label}</div>;
}

Docs Page

Create a new MDX file under content/docs/. For foo:

content/docs/foo.mdx

This automatically becomes the route /docs/foo. Every docs page must include these sections in order:

1. Frontmatter — title and description
2. Preview — one or more <ComponentPreview> blocks
3. Installation — the <InstallationCommands> block
4. Usage — import snippet + example usage
5. Props table — document every prop (markdown table or <TypeTable>)

Frontmatter

---
title: Foo
description: A brief description of the Foo component.
---

Imports

import { Foo } from '@/components/foo';
import CopyCommandButton from '@/components/copy-command-button';
import InstallationCommands from '@/components/installation-commands';
import ComponentPreview from '@/components/component-preview';

Copy Command Button

Place right after imports — gives users a one-click copy for the install command:

<div className="flex flex-col md:flex-row items-center justify-end gap-2 mb-2">
  <CopyCommandButton
    copyCommand="npx shadcn@latest add @homok/foo"
    command="npx shadcn@latest add @homok/foo"
  />
</div>

Preview

Wrap your component in <ComponentPreview>:

<ComponentPreview title="Foo default" name="foo-default">
  <Foo />
</ComponentPreview>

Installation

<InstallationCommands packageName="foo" />

Usage

Show the import and a minimal usage example:

import { Foo } from '@/components/foo'

<Foo label="World" />

Registry

Install Command

Use this command format everywhere in docs:

npx shadcn@latest add @homok/foo

The CopyCommandButton and InstallationCommands components generate this automatically when given the correct packageName.

Register in registry.json

Open registry.json at the project root and add a new entry to the items array:

{
  "name": "foo",
  "type": "registry:component",
  "title": "Foo",
  "description": "A brief description of the Foo component.",
  "dependencies": [],
  "files": [
    {
      "path": "src/components/foo.tsx",
      "type": "registry:component",
      "target": "components/foo.tsx"
    }
  ]
}

Build Artifacts

Run the build command to generate the JSON artifacts:

npm run registry:build

This produces:

• public/r/foo.json — the installable component artifact
• public/r/registry.json — updated registry index

Validate

Run a type check to make sure nothing is broken:

npm run types:check

Then verify manually:

1. Start the dev server with npm run dev
2. Open /docs/foo — check that the page renders correctly
3. Confirm the sidebar shows your new component under Components
4. Confirm the install command is correct in the docs
5. Optionally test the registry endpoint:

curl http://localhost:3000/r/foo.json

Checklist

Before merging, ensure every item is complete:

• src/components/foo.tsx exists with typed props and named export
• content/docs/foo.mdx exists with preview, install, usage, and props sections
• registry.json includes the foo entry with correct dependencies
• npm run registry:build succeeds and public/r/foo.json is generated
• npm run types:check passes
• The docs page renders correctly at /docs/foo