Getting started

Every command below is copied from a tested snippet — what you paste is what was run.

Install or copyCopy Anchor Link

For admin UI, you can install the npm package or copy individual bricks with the shadcn CLI (your app needs a components.json). Composed bricks (drawer, confirm-dialog, …) depend on @zedkit/* siblings — register the namespace once, then add bricks:

npx shadcn@latest registry add @zedkit=https://zedkit.app/r/{name}.json

The registry list grows over time; everything else stays npm-only.

Backend packages (@zedtech/zedkit-core, @zedtech/zedkit-server, @zedtech/zedkit-nest) are npm-only — install with your package manager; there is no shadcn registry copy path for them.

Stable catalog entries (shown without a badge on the docs site) follow semver on packages at 1.0.0 — see the maturity legend. Alpha and beta entries in the same package are not covered by that guarantee. Theme tokens (colors, radius, focus rings, dark/light) ship with the npm package; copied bricks are plain editable files in your tree.

See zedkit and shadcn/ui for registry vs npm trade-offs.

QuickstartCopy Anchor Link

Pick one path below. Coding agents ends with validate in the terminal; UI button paths with a visible Save button; backend and API paths with the linked catalog or tutorial page.

Coding agentsCopy Anchor Link

In your repo root:

pnpm add -D @zedtech/zedkit-ai
npx @zedtech/zedkit-ai init . --provider cursor

Those two commands take about two minutes. Ask your agent to run the setup-ai skill (it fills AGENTS.md from repo facts; 15 to 45 minutes for a typical app repo). Then:

npx @zedtech/zedkit-ai validate

First result: the validate command prints an ok line naming its structural-only scope. If it does not, see Troubleshooting.

UI button (npm package)Copy Anchor Link

In a React 19 + Tailwind v4 app. @source is relative to the CSS file: ../node_modules/… from app/globals.css or Vite src/index.css, and ../../node_modules/… from Next.js src/app/globals.css. The snippet includes both.

pnpm add @zedtech/zedkit-ui @fontsource-variable/inter @fontsource-variable/space-grotesk

Vite: wire Tailwind and kit CSS in src/index.css. Next.js App Router: put the same lines in src/app/globals.css (the layout import below loads that file).

@import "tailwindcss";
@import "@zedtech/zedkit-ui/styles.css";
@source "../node_modules/@zedtech/zedkit-ui/src/**/*.{ts,tsx}";
@source "../../node_modules/@zedtech/zedkit-ui/src/**/*.{ts,tsx}";
@source not "../node_modules/@zedtech/zedkit-ui/src/**/*.test.*";
@source not "../../node_modules/@zedtech/zedkit-ui/src/**/*.test.*";

Next.js App Router: load the fonts in src/app/fonts.ts (self-hosted, same as the site):

import "@fontsource-variable/inter";
import "@fontsource-variable/space-grotesk";

Next.js App Router: pick a look in src/app/layout.tsx so the finished app matches the site:

import "./globals.css";
import "./fonts";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" data-identity="glass">
      <body>{children}</body>
    </html>
  );
}

Render a button from the package:

import { Button } from "@zedtech/zedkit-ui";

export default function App() {
  return (
    <main className="px-page-gutter py-section-sm">
      <Button>Save</Button>
    </main>
  );
}

First result: a styled Save button in your running app. Open Button for variants, registry install, and the live preview.

UI button (shadcn registry)Copy Anchor Link

Initialize shadcn with the Radix preset (npx shadcn@latest init -y --base radix --preset nova), then add theme tokens and the button brick — no @zedtech/zedkit-ui dependency:

npx shadcn@latest add https://zedkit.app/r/theme.json
npx shadcn@latest add https://zedkit.app/r/button.json

Import the copied component:

import { Button } from "@/components/ui/button";

export default function App() {
  return (
    <main className="px-page-gutter py-section-sm">
      <Button>Save</Button>
    </main>
  );
}

First result: the same Save button, sourced from @/components/ui/button. See zedkit and shadcn/ui for updating copied files.

import { Button } from "@zedtech/zedkit-ui";

export function SaveRow() {
  return (
    <>
      <Button>Save</Button>
      <Button variant="destructive" size="sm">Delete</Button>
    </>
  );
}

Core helpers (npm only)Copy Anchor Link

In any TypeScript project:

pnpm add @zedtech/zedkit-core

First result: model errors with Result and tryCatch instead of raw try/catch — follow Model success or failure without throwing.

Server helpers (npm only)Copy Anchor Link

On a Node server or worker:

pnpm add @zedtech/zedkit-server

First result: parse env at boot with loadEnv — see Fail fast on bad environment variables.

Nest API (npm only)Copy Anchor Link

For a NestJS service, install the factory package first (peer deps in the tutorial):

pnpm add @zedtech/zedkit-nest

First result: a bootstrapped API with validation and safe errors — follow Start a safe NestJS API.

Who this is forCopy Anchor Link

You ship TypeScript apps (React UIs, APIs, content sites, or scripts) and want small, versioned packages or copied UI source in your repo — not one-off snippets from blog posts. You are fine installing from npm or running the shadcn registry when a brick is published.

When to use zedkitCopy Anchor Link

Use zedkit when a documented need matches yours: the catalog lists imports, maturity, and examples that stay aligned with the published package. Prefer your own code when the need is highly specific to one product and will not be reused.

Reach for a thin wrapper around a mature npm library when zedkit does not list the need yet (see the golden rule in the repo).

Using shadcn/ui today? Read zedkit and shadcn/ui for what the UI kit wraps, registry install vs npm, and when to stay on upstream shadcn.

Choose a packageCopy Anchor Link

Install only the packages you need. The docs index groups every catalog entry under these folders.

PrerequisitesCopy Anchor Link

• Node.js 22 or newer and pnpm 9 (same as the root README quickstart).
• UI work: React 19 and Tailwind CSS v4 in your app; follow the theme doc for tokens and the .dark class.
• Agent setup: a git repo on your machine; pick one provider flag for zedkit-ai init (cursor, claude, codex, muse, or all).

Scenario — UICopy Anchor Link

You add an internal admin to an existing React 19 app with Tailwind v4 and need consistent tokens before you ship screens.

1. Run UI button and wire CSS so buttons are not unstyled (npm: kit CSS; registry: theme registry item).
2. Install the npm package when you want the full kit; copy single bricks from the registry when you must edit source — zedkit and shadcn/ui compares both paths.
3. For sidebar, tables, and forms together, follow Build an admin dashboard.

Scenario — backendCopy Anchor Link

You ship a Node worker or API and want env validation before you handle traffic.

1. Run Server helpers and wire loadEnv from the server catalog page linked in that section.
2. For NestJS, run Nest API and follow Start a safe NestJS API (peer deps listed there).

Scenario — SEOCopy Anchor Link

You ship a Next.js site or content app and want sitemap, metadata, and structured data without ad hoc tags.

1. Install @zedtech/zedkit-seo with your package manager (npm-only). Use @zedtech/zedkit-payload-seo when Payload is your CMS.
2. Start from Build localized page metadata, or follow Add SEO to a Next.js app for robots, sitemap, and JSON-LD in one pass.

Scenario — coding agentsCopy Anchor Link

You inherit a monorepo with no agent instructions. You only need consistent skills for Cursor today.

1. Run Coding agents with --provider cursor.
2. Open the AI setup catalog page and run validate from the install tabs if you prefer copy from there.
3. Commit the files init created; re-run validate after you edit skills.

Next, add UI only when you start an admin screen — install @zedtech/zedkit-ui then, not on day one.

TroubleshootingCopy Anchor Link

Next stepsCopy Anchor Link

• Catalog depth: pick a need from the docs index four areas; every need page has install tabs and a usage example.
• Tutorials: Build an admin dashboard, Start a safe NestJS API, Add SEO to a Next.js app, Set up your coding agents, zedkit and shadcn/ui.
• Machine-readable index: public/llms.txt lists the same URLs for agents.