Publish a registry

A registry distributes source files, package requirements, and provider metadata as static JSON artifacts.

File format

chkit uses the shadcn registry envelope with registry:item items and registry:file files. chkit-specific metadata lives under meta.chkit.

Format version 1 supports self-contained TypeScript templates. It does not resolve registryDependencies, transform UI imports, or run template installation hooks. Unknown fields and unsupported item types fail validation. A general shadcn UI registry is not a compatible chkit registry.

Create a source template

For a minimal example, save this as registry/demo/index.ts:

import { definePipeline, defineStream, rawRows, rawTable } from '@chkit/plugin-ingest'

export const demoEventsRaw = rawTable({ database: 'default', name: 'demo_events_raw' })

const events = defineStream({
  id: 'demo.events',
  destination: demoEventsRaw,
  async *read() {
    yield { rows: rawRows([{ id: 'example', message: 'Registry installed' }], (event) => event.id) }
  },
})

export const demo = definePipeline({ id: 'demo', streams: [events] })

Use relative imports inside a larger provider directory so it remains movable with chkit add --path. The entry must explicitly export every schema object and active pipeline listed in the manifest; wildcard exports do not satisfy the builder’s export check.

Declare the catalog

Save this as registry/registry.json:

{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "example-providers",
  "homepage": "https://example.com",
  "items": [
    {
      "name": "demo",
      "type": "registry:item",
      "title": "Demo",
      "description": "A local fixture source for testing registry installation.",
      "dependencies": [
        "@chkit/core@^0.2.0-beta.8",
        "@chkit/plugin-ingest@^0.2.0-beta.8"
      ],
      "files": [
        {
          "path": "demo/index.ts",
          "type": "registry:file",
          "target": "src/integrations/demo/index.ts"
        }
      ],
      "meta": {
        "chkit": {
          "formatVersion": 1,
          "version": "0.1.0",
          "language": "typescript",
          "license": "MIT",
          "chkit": "^0.2.0-beta.8",
          "ingest": "^0.2.0-beta.8",
          "clickhouse": ">=25.3.0",
          "root": "src/integrations/demo",
          "entry": "index.ts",
          "exports": ["demoEventsRaw", "demo"],
          "resources": [
            {
              "name": "events",
              "description": "One fixture event per full read.",
              "scopes": [],
              "strategy": "full"
            }
          ],
          "env": {}
        }
      }
    }
  ]
}

Each source files[].path is relative to the manifest’s directory. target is the default consumer-project path and must sit inside meta.chkit.root. entry is relative to that root. Paths must be normalized relative paths without .. segments.

The item name registry is reserved because registry.json contains the catalog.

Metadata and dependencies

Field under meta.chkit	Meaning
formatVersion	Registry metadata format; currently 1
version	Immutable semantic version of this template
language	Currently typescript
license	License for the copied source
documentation	Optional HTTP(S) URL of the app’s integration guide; shown by CLI list and inspect
logo	Optional HTTP(S) URL of the app’s logo; included in discovery metadata
chkit, ingest, clickhouse	Supported CLI, ingestion package, and ClickHouse version ranges
root, entry, exports	Installation directory, provider entry, and explicit public exports
resources	Resource names and descriptions, read scopes, sync strategy (full, timestamp, or cursor), optional title, default table, and endpoints with method, path, and provider documentation URL
authentication	Authentication method, required env names, ordered setup steps, and the provider’s credential setup documentation URL
views	Derived views with a name, source resource source, and description; these reuse synced records
sync	Sync description, external schedule, and deletions behavior
env	Environment variable names mapped to example values, such as {"ATTIO_API_TOKEN": ""}
fileHashes	SHA-256 values keyed by target path; generated by the builder

Resource strategies describe selection: full performs complete scan cycles, including scans with completion checkpoints; timestamp selects time windows; cursor follows checkpointed provider state, such as a change token or a resumable snapshot traversal. Describe restart behavior, cursor lifetime, and deletion handling in sync. Metadata does not configure the runtime strategy. Older strict registry clients accept only full; templates advertising new labels must require a CLI version that accepts them.

Declare npm dependencies as package@semver-range. Every item must include @chkit/core and @chkit/plugin-ingest. Git URLs, local dependencies, and package-manager aliases are outside this format.

Use blank values for secrets in env. Never include credentials in metadata or source artifacts. State resource limitations in the item’s description and copied README, including deletion behavior and inaccessible API families.

Package fixture tests

Keep tests under the provider’s tests/ directory and mark their file entries with role: "test":

{
  "path": "demo/tests/demo.test.ts",
  "type": "registry:file",
  "target": "src/integrations/demo/tests/demo.test.ts",
  "role": "test"
}

These files receive content hashes like other source files; the installer includes them only with --with-tests. Optional item-level devDependencies lists test tooling, such as @types/bun@^1.2.0, using the same package@semver-range format. Those dependencies are added to the consumer’s development dependencies only when tests are selected.

Tests should use fixture payloads and mocked service clients so consumers can run them without provider credentials. Avoid repository-relative imports, unpublished workspace tooling, and live-database prerequisites in the distributed test set. Repository-only packaging or database tests can live in the same source folder, excluded from the manifest’s files.

Build and test locally

chkit registry build registry/registry.json --output ./registry-output
chkit registry list --registry ./registry-output
chkit registry inspect demo --registry ./registry-output

The build emits:

registry-output/
  registry.json
  demo.json
  demo/
    0.1.0.json

registry.json is the discoverable catalog. demo.json points consumers to the current item contents. demo/0.1.0.json contains that specific version. Built items include source content and its hashes, so installation does not need access to the source repository.

From a separate test project with package.json, preview installation and then inspect the copied code:

chkit add /absolute/path/to/registry-output/demo/0.1.0.json --dry-run
chkit add /absolute/path/to/registry-output/demo/0.1.0.json --yes
chkit ingest list
chkit generate --name add-demo

Registry validation checks packaging and declared entry exports. Test each provider’s pagination, errors, identities, and replay behavior with fixtures; validate the generated schema and queries against a development database before publishing.

Publish immutable versions

Host the output directory on an HTTP(S) static host. Consumers can use its catalog URL with --registry or install a built item URL directly.

Keep every published <name>/<version>.json available. The builder rejects an attempt to write different bytes to an existing version file. Increment meta.chkit.version for any released template change, including source, dependencies, or metadata. Preserve older version files when building a deployment from a clean checkout; an empty output directory alone cannot establish what was previously published.

Provider layout in the chkit repository

Each official provider has one self-contained directory:

registry/
  attio/
    manifest.json
    README.md
    index.ts
    client.ts
    config.ts
    pipeline.ts
    sources/
      objects.ts
      object-attributes.ts
      records.ts
      lists.ts
      list-attributes.ts
      entries.ts
      notes.ts
      tasks.ts
      members.ts
    tests/
      attio.test.ts
      fixtures.ts
      install.e2e.test.ts
    releases/
      0.1.0.json
      0.1.1.json
      0.1.2.json

Each sources/ module keeps a resource’s reader and schema together. Shared request behavior stays in client.ts; selection and destination settings stay in config.ts.

manifest.json contains one registry item. Its source paths are relative to the provider directory (for example, sources/notes.ts); target paths still use the full consumer path such as src/integrations/attio/sources/notes.ts. The repository’s catalog loader discovers these provider-local manifests and aggregates them for the build, CLI artifacts, and documentation. bun scripts/build-registry.ts builds the official catalog; it does not require a handwritten catalog at the registry root.

Released artifacts are committed under registry/<name>/releases/<version>.json. The official CLI reads provider directories and manifests from GitHub and installs those committed release artifacts directly. The documentation build also copies that history into apps/docs/public/r/<name>/ before building the current catalog and latest aliases. History and the source are colocated without installing release files into consumer projects.

After validating a new release artifact, copy its immutable file into the provider’s releases/ directory and commit it with the corresponding source and version change. Do not hand-edit the artifact or commit generated latest aliases. Adding a provider or template version does not require an npm package release; changes to CLI behavior do. The docs build also publishes a static catalog at https://chkit.obsessiondb.com/r/registry.json for web and custom-registry use.

Add an app to the official documentation

Each provider declared in registry/<name>/manifest.json has a guide at apps/docs/src/content/docs/integrations/<name>.md or .mdx. Set its title to Integrating ClickHouse with <App title> and write a specific one-sentence description. Give the sidebar a short app label.

Set meta.chkit.documentation to https://chkit.obsessiondb.com/integrations/<name>/. Every official app requires a provider logo: store the official asset in apps/docs/public/logos/, record its source in that directory’s README.md, and set meta.chkit.logo to its full HTTPS URL on the docs site. Preserve the asset’s proportions and brand colors.

Every official manifest includes authentication setup steps, resource titles and destination tables, provider endpoint references, derived views, and sync/deletion metadata. Credential setup must explain where an administrator creates a token in the source system, which permissions it requires, and how the execution environment receives it. Link to the provider’s current instructions and verify the UI path before publishing.

Every guide also explains installation, migrations, raw and projected fields, pagination, repeat runs, failure recovery, unsupported data, and scheduling. Verify the claims against the installed readers and schema. A name-swapped introduction alone is not a complete integration guide.

Use RegistryReference in MDX to render shared reference sections from the provider manifest:

import RegistryReference from '../../../components/RegistryReference.astro';

<RegistryReference name="attio" section="authentication" />
<RegistryReference name="attio" section="scopes" />
<RegistryReference name="attio" section="resources" />

The other sections are overview, views, and sync. The raw-Markdown build expands the same components for agents. The resources section documents every declared resource; handwritten guides must include each exact resource name in backticks. Keep the explanation of provider-specific behavior as prose alongside the generated reference tables.

The integration list, its agent-readable Markdown, CLI discovery, and search structured data read the same manifest. The docs build checks that every official item has its guide, description, resource coverage, and required local logo asset. New guides also enter site search, the sitemap, and llms.txt automatically.

bun run scripts/check-registry-docs.ts
bun run --cwd apps/docs build

Preview the app listing and guide in both themes, check the rendered resource tables, and verify the guide appears in apps/docs/dist/_raw/index.md and apps/docs/dist/llms.txt. Metadata changes require a new immutable registry version just like source changes.

Related pages

• chkit registry: command reference and build flags.
• chkit add: consumer installation behavior.
• Test a source: ingestion correctness beyond packaging.
• Provider templates: template ownership and customization.