Building a package · kitr docs

Every package on this site, official or not, is an ordinary npm package with three additions: a kitr block in its package.json, a docs folder, and optionally an examples folder. Nothing is registered by hand. Publish it with the kitr-package keyword and it can be listed here.

The manifest

{
  "name": "kitr-stripe",
  "version": "1.0.0",
  "keywords": ["kitr", "kitr-package"],
  "files": ["dist", "docs"],
  "kitr": {
    "name": "stripe",
    "title": "Stripe",
    "summary": "Take card payments and subscriptions, with checkout pages you can restyle.",
    "category": "backend",
    "runsOn": "both",
    "builtOn": ["stripe"],
    "requires": ["server"],
    "docs": "docs"
  }
}

Field	Required	Description
`name`	yes	The short name people type: `kitr add stripe`.
`title`	yes	Display name on this site.
`summary`	yes	One sentence, 140 characters at most, on what it does for the app. See below.
`category`	yes	One of `data-fetching`, `app-state`, `backend`, `realtime`, `interface`, `forms`, `auth`, `pages`, `platforms`, `device`, `insights`, `dev-tools`. Sets the colour and filter on the packages page.
`runsOn`	yes	`client`, `server` or `both`. Shown as a badge.
`builtOn`		Upstream libraries it wraps, shown as "Built on".
`requires`		Other kitr packages that must be added first.
`client`		`true` if it needs a React frontend, so server-only projects refuse it.
`docs`		The docs folder, relative to the package root. Include it in `files`.

Writing the summary

The summary is the first thing a beginner reads on the packages page, so it answers what will this do for my app? in plain words:

Good: "Show rows of data with sorting, paging and filters that stay in the URL."
Not: "TanStack Table v9 with URL-bound state." That only helps people who already know TanStack.

Put library names in builtOn, where they show as a separate note.

Docs

docs/
├── index.md   # overview: what it's for, install, a working example, guides, configuration
└── api.md     # reference: every export, option and type

Each file starts with frontmatter:

---
title: Stripe
description: Take card payments and subscriptions, with checkout pages you can restyle.
order: 1
---

The description of index.md must match the manifest summary. Follow the order the official packages use, so readers always know where to look:

What it's for, in two or three sentences, and when not to use it.
Install: the kitr add command and what it changes.
A first working example they can paste.
Guides for the common tasks.
Configuration: a table of every option with its default.
Next steps: the API page and the upstream docs.

Shell blocks that only contain kitr commands get the package-manager picker automatically. Link to other packages as /packages/<name>.

Check the manifest and docs before publishing:

kitr package:check

First time? Run npm i -g kitr once. Inside a project, the global kitr runs your project's own version.

Live examples

Each examples/<name>.tsx becomes a live demo at the top of the package page, running in a sandboxed frame with a refresh button so readers can see what persists.

// examples/checkout.tsx
export const meta = {
  title: 'Checkout',
  description: 'Pay with a test card. Reload to see the order is kept.',
}

export default function Example() {
  return <CheckoutButton priceId="price_test_123" />
}

Anything an example stores in the browser is namespaced to it, so examples never see each other's data.

Setup with kitr add

To let kitr add wire your package, export a configure function that receives the project and a set of codemods (install dependencies, add a provider to kitrrc.ts, write config/<name>.ts, append to AGENTS.md). Official packages define theirs in the CLI today; the same hook will load from your package in a coming release.

Publishing

npm publish

Use the kitr-package keyword. Community listings are on the way: a weekly sync will pick up packages with that keyword and list them under Community, with a health badge based on recent releases and the kitr versions they support.