Quickstart - n3wth docs

Kit distributes React and TypeScript source through a shadcn-compatible registry. Installing an item copies files into your application; import those local files and maintain your changes there. The website's @n3wth/kit workspace is private, so it is not the component package to install with npm.

Prerequisites#

Use a React application with TypeScript, Tailwind CSS, and a working @/* import alias. These instructions assume Tailwind v4 and shadcn aliases that place UI components under @/components/ui and utilities under @/lib/utils. Next.js projects need a client boundary for interactive examples.

For work inside the source repository, its instructions require Node 24 and npm 11.19.1. Those are repository tooling requirements, not a declared minimum version for every copied component.

Add a button#

Run these commands from your application directory. Skip initialization if you already have a working components.json.

npx shadcn@latest initnpx shadcn@latest add https://kit.n3wth.com/r/button.json

The button item references https://kit.n3wth.com/r/cn.json, which declares clsx and tailwind-merge. Inspect the generated files before accepting overwrites of existing components.

The component imports cn from @/lib/utils. The registry utility is named cn.ts and has no explicit destination override. If your application already has shadcn's cn helper at the configured utils alias, retain it. Otherwise, ensure that @/lib/utils exports this implementation:

import { clsx, type ClassValue } from 'clsx'import { twMerge } from 'tailwind-merge'export function cn(...inputs: ClassValue[]) {  return twMerge(clsx(inputs))}

Supply the component styles#

The button contains Tailwind classes, but also references application CSS variables and custom classes. Installing its JSON does not install a complete stylesheet. The n3wth style item defines standard shadcn variables; it does not define all the --color-* and --glass-* variables used by the component source.

For a minimal dark button example, add the following to your loaded global stylesheet after its existing Tailwind import. These values are an application example, not a complete Kit theme. If your application already defines these tokens, reuse its definitions.

:root {  --color-white: #fafafa;  --color-bg: #111111;  --color-grey-400: #a3a3a3;  --glass-bg: rgb(255 255 255 / 0.05);  --glass-border: rgb(255 255 255 / 0.18);  --glass-highlight: rgb(255 255 255 / 0.35);}.focus-ring:focus-visible {  outline: 2px solid var(--color-white);  outline-offset: 3px;}

The primary variant also includes glow-white. Define that optional visual effect in your application or remove the class from your local copy. Other items need additional tokens; inspect their source before adding them.

Render and customize#

Save this in an application component and render it from a page:

'use client'import { useState } from 'react'import { Button } from '@/components/ui/button'export function Counter() {  const [count, setCount] = useState(0)  return (    <Button      type="button"      variant="secondary"      size="md"      touchTarget      className="rounded-lg"      onClick={() => setCount(value => value + 1)}    >      Count: {count}    </Button>  )}

Use props for existing variants, className for local overrides, and edit the copied source when behavior must change. cn merges the component classes with your overrides. Reinstalling with overwrite can replace those edits; review the diff before updating.

Button reference#

Prop	Accepted values	Default or behavior
`variant`	`primary`, `secondary`, `ghost`, `glass`	`primary`
`size`	`sm`, `md`, `lg`, or an object with `base`, `md`, `lg`	`md`; responsive objects build breakpoint classes dynamically
`isLoading`	Boolean	`false`; shows a spinner and disables the native button
`leftIcon`, `rightIcon`	React nodes	Loading replaces the left icon and hides the right icon
`touchTarget`	Boolean	`false`; adds minimum width and height of 44px
`asChild`	Boolean	`false`; clones one valid child element
`className`	String	Merged after component classes

With asChild, put link attributes and event handlers on the child: the implementation clones its class, ref, and content but does not forward the remaining button props. A loading anchor is not automatically disabled.

<Button asChild variant="secondary">  <a href="/kit/catalog">Browse the catalog</a></Button>

Troubleshooting#

Symptom	Check and resolution
Cannot resolve `@/lib/utils`	Check `components.json`, TypeScript aliases, and the installed utility location; expose `cn` at the path the component imports.
Colors or borders are missing	Define the variables used by the copied component and ensure the global stylesheet is loaded.
Responsive size does not change	Button constructs breakpoint classes dynamically. Use literal responsive classes in your application or explicitly include the generated classes in your Tailwind source configuration.
Hook or event-handler error in Next.js	Import interactive components from a module marked `'use client'`. Registry sources do not consistently declare their own client boundary.
Installing a dependency resolves the wrong item	Some entries use bare dependency names. Install the needed Kit item with its full registry URL and inspect the resulting imports.

Run your application's typecheck and build, then check keyboard focus and interactions in a browser. Continue with the catalog, registry authoring, or optional AI context.