Custom Registry

A registry is just a folder of JSON files — one <name>.json per component, split under a <styleSystem>/ subfolder. kosmesis add reads it from a local directory or an http(s):// URL; there's no server, database, or account required. This is for an internal design system, a client's own variant of a Kosmesis component, or trying out a change before publishing it anywhere.

The CLI has three commands for this — you never have to hand-write the inlined JSON kosmesis add fetches, or the script that builds it:

Neither init nor build needs an existing components.json — they operate on the registry you're authoring, not on a Kosmesis app. add/remove/list do need one, since that's where a consumer project records which registries it trusts.

Quickstart: your first component, end to end

npx kosmesis registry init my-registry

my-registry/
  registry.json           # the index — one entry per component
  src/
    example-button.tsx    # a real, working example component

cd my-registry
kosmesis registry build

npx kosmesis registry add acme ./path/to/my-registry/dist/r
npx kosmesis add @acme/example-button

That's the whole loop. Everything below is reference material for scaling this up: serving it over HTTP, style-system-specific dependencies, cross-component dependencies, and the exact JSON shape.

kosmesis registry build reference

Besides one <name>.json per component, the build writes <styleSystem>/index.json (every item, without file content, so kosmesis outdated can check the whole registry in one request) and updates registry-lock.json next to your index (see Versioning).

Serving it for real

Once the build output is worth sharing beyond your own machine, upload it to any static file host (S3 behind a CDN, GitHub Pages, an internal file server — anything that serves plain files over HTTP) and point teammates at the URL instead of a local path:

npx kosmesis registry add acme https://ui.acme.internal/r

Nothing else changes — kosmesis add @acme/example-button resolves the same way whether registries["@acme"] is a path on disk or a URL. This repo's own docs/public/r (built by pnpm registry:build, the same idea as kosmesis registry build but wired into this monorepo's own scripts) is exercised as a local directory the same way before it's ever deployed to kosmesis.praxisjs.org.

Managing registries

A project can mix addresses freely in one call: kosmesis add button @acme/example-button installs button from the default registry and example-button from @acme in the same run.

Dependencies: other components, npm packages, and dev-only npm packages

If one of your components imports another one from the same registry, list it under registryDependencies instead of copying its source in — kosmesis add resolves the full closure and writes every dependency's files too. Add a second item to the registry.json kosmesis registry init scaffolded, alongside example-button:

{
  "name": "example-card",
  "registryDependencies": ["example-button"],
  "files": [{ "path": "src/example-card.tsx", "type": "registry:ui" }]
}

kosmesis registry build checks this at build time — it fails loudly, naming the exact component, if registryDependencies points at a name that isn't also in the index.

registryDependencies only resolves within the same registry/namespace — there's no cross-registry lookup. If your component depends on something from the public Kosmesis registry, either vendor that component's source into your own registry, or note it in your docs so consumers run a second kosmesis add for it.

npm packages (as opposed to other registry components) go under dependencies or devDependencies instead, and are installed automatically with the consumer's detected package manager — dependencies ships with the consumer's app, devDependencies is for build/type-check-only packages (type declarations, codegen tools) and gets installed with -D/--save-dev:

{
  "dependencies": ["some-npm-package"],
  "devDependencies": ["@types/some-npm-package"]
}

kosmesis registry build reads every component's imports and fails, listing each one, when a component imports something it doesn't declare:

• an npm package must be in dependencies, or in devDependencies when every import of it is import type (it's erased from the build, so only tsc needs it). The four packages every PraxisJS app already has (@praxisjs/core, @praxisjs/decorators, @praxisjs/jsx, @praxisjs/runtime) are the only ones that don't need declaring.
• a relative import (./example-button) must point at one of the component's own files or a file of one of its registryDependencies, since kosmesis add writes them all into the same directory.

@/ project aliases (@/lib/utils) and node: builtins aren't checked.

If a package ends up listed as a runtime dependencies entry by one component and a devDependencies entry by another (in the same kosmesis add call), the runtime one wins — it needs to ship, not just type-check, so it's installed once, without -D.

Versioning

Give every item a version (semver) and bump it whenever you change the item's files or dependencies. Projects that installed it see the new version in kosmesis outdated, and kosmesis update shows them the diff (see Updating Components).

{
  "name": "example-button",
  "version": "1.1.0",
  "type": "registry:ui",
  "files": [{ "path": "src/example-button.tsx", "type": "registry:ui" }]
}

kosmesis registry build keeps you honest with registry-lock.json, which it writes next to your index: each item's version plus a hash of everything a consumer receives (each file's content and target, and its dependencies, devDependencies and registryDependencies; not title or description). Commit it. On the next build:

• an item whose content changed but whose version didn't fails the build, naming the item;
• a version lower than the locked one fails the build;
• a version that isn't valid semver fails the build;
• otherwise the lock is updated to the new versions and hashes.

The first build after adding versions just creates the lock. Bumping a version without changing anything is allowed (for example, to re-announce a component).

version is optional for a registry you serve yourself. An item without one builds with a warning and is served unversioned: projects that install it see its version as unknown, never as an update, though kosmesis update <name> still compares its content. Registries built with older Kosmesis versions keep working the same way.

The built item also carries a hash for each file (SHA-256 of its content, line endings normalized), which you never write by hand.

The full JSON shape

For reference, here's every field a built <styleSystem>/<name>.json can have — this is what kosmesis registry build produces from a registry.json entry, not something you write by hand:

{
  "name": "example-button",
  "version": "1.1.0",
  "type": "registry:ui",
  "title": "Example Button",
  "description": "Optional, human-readable.",
  "dependencies": ["some-npm-package"],
  "devDependencies": ["@types/some-npm-package"],
  "registryDependencies": ["some-other-component"],
  "files": [
    {
      "path": "src/example-button.tsx",
      "type": "registry:ui",
      "target": "example-button.tsx",
      "hash": "sha256-3b5d5c37...",
      "content": "// inlined file source"
    }
  ]
}