# CS Registry

CS Registry is a private shadcn-compatible registry for installable React components, composite blocks, and utilities. It is implemented with Next.js 16, React 19, TypeScript, Tailwind CSS v4, and Base UI. The registry currently contains 20 items.

## Primary URLs

- Catalog: https://registry.ceskysoftware.cz/
- Setup guide: https://registry.ceskysoftware.cz/docs
- Registry architecture reference: https://registry.ceskysoftware.cz/docs/registry
- Per-item documentation: https://registry.ceskysoftware.cz/docs/{name}

## Installing Items in a Consumer Project

Initialize shadcn if the project does not yet have `components.json`:

```bash
npx shadcn@latest init
```

Configure the `@cs` namespace in the consumer project's `components.json`:

```json
{
  "registries": {
    "@cs": {
      "url": "https://registry.ceskysoftware.cz/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}
```

Store the token in the consumer project's `.env.local` using the same variable name:

```env
REGISTRY_TOKEN=your-registry-token
```

Install an item by name:

```bash
pnpm dlx shadcn@latest add @cs/form
pnpm dlx shadcn@latest add @cs/action-result
```

The shadcn CLI resolves `registryDependencies`, installs package dependencies, and writes each source file to the `target` declared by the registry manifest. Installed files belong to the consumer project and may be customized there.

## Authentication and Endpoints

The direct distribution endpoints require either `Authorization: Bearer <token>` or `?token=<token>`:

- `GET /r/{name}.json`: installable manifest for one item, including inline source code.
- `GET /r/registry.json`: metadata-only index of all items.
- `GET /api/r/{name}`: dynamic application route that reads the generated manifest for one item.

Do not place tokens in URL paths. Use the Authorization header for shadcn registry configuration. On the registry server, authentication expects `REGISTRY_TOKEN`; `CESKYSOFTWARE_UI_TOKEN` remains a legacy fallback.

## Repository Structure

```text
registry/
├── cs/
│   ├── ui/              # Installable UI components
│   ├── utils/           # Installable utility functions and types
│   ├── blocks/          # Installable composite blocks
│   ├── examples/        # Usage snippets and API reference metadata
│   └── previews/        # Documentation-only component previews
├── registry.json        # Item metadata, targets, and dependencies
├── scripts/build-registry.mjs
├── public/r/            # Generated distribution manifests
└── proxy.ts             # Authentication for /r/*.json
```

## Registry Item Conventions

`registry.json` is the canonical registry index. Each item has a name, type, description, source file list, optional target paths, package dependencies, and registry dependencies.

Supported item types in this repository are:

- `registry:ui`: reusable UI components.
- `registry:component`: composite components or client helpers.
- `registry:lib`: utilities, types, and helpers.

Use `@cs/{name}` for dependencies on items in this registry. Use `@shadcn/{name}` for dependencies provided by the configured shadcn registry.

For each documented item, `registry/cs/examples/{name}.json` provides:

- `imports`: import example.
- `usage`: usage example.
- `api`: structured API reference metadata for exports, props, parameters, return values, signatures, or methods.

`registry/cs/previews` contains documentation previews only. Preview modules are dynamically loaded by the docs UI and must not be added to installable item manifests.

## Build and Distribution Flow

1. Add or edit source files under `registry/cs`.
2. Register the item or changed file metadata in `registry.json`.
3. Add or update its example JSON and API metadata in `registry/cs/examples`.
4. Run `pnpm registry:build`.
5. The generator recreates `public/r/{name}.json` with inline source file content and recreates `public/r/registry.json`.
6. The deployed Next.js application serves the catalog, documentation, and authenticated registry manifests.

Do not edit files in `public/r` manually. They are generated output.

## Agent Guidance

- Read `registry.json` before adding or changing an installable item.
- Keep source code, metadata, example JSON, public API documentation, and registry dependencies synchronized.
- Prefer existing local patterns and imports such as `@/components/cs/*` and `@/lib/cs/*`.
- Add English JSDoc for public exports and custom props.
- Run `pnpm registry:build` after changing registry metadata or installable source files.
- Validate JSON example files after editing them.

## Useful Commands

```bash
pnpm dev
pnpm registry:build
pnpm app:build
pnpm build
pnpm exec tsc --noEmit
```