Skip to content
opsinjs
Edit this page

opsinjs

Registry

opsinjs ships as a shadcn-spec registry of source you copy and own, not as an npm package you depend on.

npx shadcn add writes a component's source into your repository. The registry follows shadcn's specification without extending it, so the shadcn CLI and its MCP server need no adapter.

All 60 catalogue ids are shipped, so each installs and renders. None has had an independent accessibility review or any clinical review, and none is for a production health surface. Nothing is released yet.

What you get and what it costs

You getYou pay
Readable source, such as RangeBar's answer to a missing reference rangeUpdates never arrive on their own
No peer dependencies and no lockfile conflictsMaintenance and security fixes, with no npm audit for copied files
Changes made by editing a fileCopies of one component drift apart silently

What is served

PathContents
/r/registry.jsonEvery item, without file contents. The CLI and MCP server read it first
/r/<name>.jsonOne item, with its files inlined
/r/styles/<style>/<name>.jsonThe same item at a named style
/r/themes/<preset>.jsonA theme, with cssVars and no files
/r/index.jsonStatus, category, aliases and the review notice for each id

The catalog and its items follow shadcn's schemas. An item's name is also its catalogue id, docs path and file name, and its description is plain English for a patient. Fields shadcn lacks, such as implemented, status and since, sit under meta.opsinjs, so items validate anywhere. A component is a registry:ui item that also carries lib/opsinjs.ts and lib/status.ts.

Namespace and commands

components.json
{
  "registries": {
    "@opsinjs": "https://opsinjs.pensievelabs.org/r/{name}.json"
  }
}

{name} is required. Add the block even when you install by full URL, because 21 items name their siblings as @opsinjs/<name> in registryDependencies, and the CLI cannot follow them without it. A namespace is a local alias, not a reservation, so read the URL of any namespace you did not write.

CommandUse
npx shadcn@latest add @opsinjs/result-cardInstall an item and its registry dependencies
npx shadcn@latest add @opsinjs/result-card --dry-runList the files it would write
npx shadcn@latest view @opsinjs/result-cardRead the source before you accept it
npx shadcn@latest add @opsinjs/result-card --diffCompare your copy with the current upstream
npx shadcn@latest search @opsinjs -q "range"Search names, titles and descriptions

Never run add --all against opsinjs, and never --overwrite before reading --diff. There is no opsinjs CLI, and the check-theme and doctor commands are proposed, not built.

Taking upgrades

There is no npm update, and nothing in a copied file records its version.

  1. Run add in its own commit, naming the item and the date. That commit is the only record of what you took.
  2. Read the changelog, then run add --diff to see what would change.
  3. Decide per hunk. Overwrite an unedited file, re-apply light edits on top, and three-way merge heavy ones against your install commit, for example with git merge-file --diff3 mine.tsx base.tsx theirs.tsx.
  4. Upgrade the token layer with the components, then re-run your tests, your contrast checks and a greyscale check.

No upgrade has been exercised yet, because nothing has been released. Prefer composition to editing, because a wrapper never conflicts.

Running your own registry

Publishing components beside opsinjs needs no fork. A registry is a flat registry.json plus one JSON file per item at a URL matching {name}, and shadcn build writes the item files. Pick a namespace nobody else will want, such as @acme-health, and reference opsinjs items by full URL or a configured namespace, never a bare name.

Fork the repository only to change tokens, generators or doctrine. First change its name, namespace, preset prefix and site URL. Never edit generated output, and run pnpm run generate && pnpm run contrast && pnpm run check after every upstream merge. Forking the status vocabulary or the clinical doctrine needs clinical sign-off.

Proposed packages

Five npm packages are proposed as specifications, and none is published. The repository's packages/ folder holds only a README, and the registry stays the way opsinjs is distributed.

PackageProposed to hold
@opsinjs/colorOKLCH, gamut mapping, APCA, WCAG 2.2 and deriveTheme(), for a contrast check in CI. The maths already lives in lib/color/
@opsinjs/motionSpring solving and linear() generation
@opsinjs/reactThe components as a dependency, for teams that cannot vendor source. Whether to publish it is undecided
@opsinjs/presetThe @theme inline mappings
@opsinjs/tailwind.cssThe token stylesheet as a versioned import