llms.txt

Machine-readable project guidance, presented for comfortable reading.

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:

npx shadcn@latest init

Configure the @cs namespace in the consumer project's components.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:

REGISTRY_TOKEN=your-registry-token

Install an item by name:

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

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

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