Registry authoring - n3wth docs

Use this workflow when contributing source that consumers will copy through shadcn. The authoritative input is apps/kit/registry.json; generated items live in apps/kit/public/r/. Website components in app/_components are not registry entries.

Prerequisites#

Work on a feature branch in a checkout with Node 24 and npm 11.19.1. Install repository dependencies with npm ci at the root. Read the root and Kit AGENTS.md files before editing. These instructions describe contributor commands; registry generation writes files.

Add source and a manifest entry#

For a UI item, create a TypeScript React file under apps/kit/registry/new-york/<name>/. Export the component by name and keep its imports usable in a consumer project. Use a client directive when the entry itself requires a client boundary.

For example, this standalone source can live at registry/new-york/status-message/status-message.tsx relative to apps/kit:

import type { ReactNode } from 'react'import { cn } from '@/lib/utils'export interface StatusMessageProps {  children: ReactNode  className?: string}export function StatusMessage({ children, className }: StatusMessageProps) {  return (    <p role="status" className={cn('text-sm', className)}>      {children}    </p>  )}

Append the following object to the existing manifest's items array. This is an authoring example, not an item currently published by Kit.

{  "name": "status-message",  "type": "registry:ui",  "title": "Status Message",  "description": "A status message announced when its content changes.",  "registryDependencies": ["https://kit.n3wth.com/r/cn.json"],  "files": [    {      "path": "registry/new-york/status-message/status-message.tsx",      "type": "registry:ui"    }  ]}

The files array determines what is distributed. An unlisted helper or index file is not part of the item. Existing entries generally point directly at their implementation files; do not assume a barrel file is generated.

Manifest reference#

Field	Use in this registry
`$schema`	Root schema is `https://ui.shadcn.com/schema/registry.json`
`name`, `homepage`	Root registry identity: `n3wth` and `https://kit.n3wth.com`
`items`	Array of named registry entries
Item `name`	Identifier used for the generated JSON filename
Item `type`	`registry:ui`, `registry:block`, `registry:hook`, `registry:lib`, or `registry:style`
`title`, `description`	Human-readable item metadata
`dependencies`	npm dependencies, such as `gsap` or `clsx`
`registryDependencies`	Other registry items; use full Kit URLs for unambiguous references
`files`	Source paths relative to `apps/kit`, with a registry file type
`cssVars`	Used by the `n3wth` style entry for theme, light, and dark variables

List every external dependency the consumer needs. Include supporting files for relative imports, as the shape and composite-shape entries do. Verify aliases such as @/lib/utils against a consumer project; listing cn alone does not prove that the helper lands at the imported path.

Generate and review#

From the repository root:

npm run registry:build --workspace=@n3wth/kit

This script invokes npx shadcn@latest build. The generated item embeds source text in files[].content; review the JSON as well as the TypeScript. registry:dev invokes the same tool with --watch for repeated generation.

Before a clean rebuild at this revision, resolve the missing registry/new-york/icon/icon.tsx source referenced by the manifest. Its checked-in JSON artifact does not repair that missing input. Do not discard unrelated artifacts to hide a build problem.

Validate before publishing#

Confirm every manifest path exists and every relative import has a distributed file.
Inspect each item's npm and registry dependencies, including transitive dependencies.
Compare generated files[].content against source; investigate unexpected artifact changes.
Install the generated item into a disposable, configured React application and verify aliases, styles, exports, and client boundaries there.
Run repository checks from the root and the consumer application's checks. Review keyboard behavior and any loading, error, or motion states in a browser.

The repository's full check command is:

npm run check

It includes builds and can write outputs. Generation and checks prepare a change for review; they do not publish the registry. Follow the repository deployment process and verify the deployed item URL before announcing availability.

Troubleshooting#

Failure	Resolution
Builder cannot read a source file	Check `files[].path` against the checkout, including the known missing icon source.
Installed component has a missing module	Add omitted npm or registry dependencies and check consumer aliases.
Published JSON contains old code	Compare source with the generated artifact, regenerate it, and verify the deployed response.
Component renders without expected styling	Document its required CSS variables and custom utility classes, or distribute the needed styling through an appropriate registry entry.

See the catalog for existing entry groups and quickstart for consumer-side checks.