# Quickstart

> Copy a Kit component into your React application. Then configure its styles.

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`.

```bash
npx shadcn@latest init
npx 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:

```ts
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.

```css
: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:

```tsx
'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.

```tsx
<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](/kit/catalog), [registry authoring](/kit/registry-authoring), or [optional AI context](/kit/ai-and-cli).

## Sources

- [Registry manifest](https://github.com/n3wth/n3wth/blob/main/apps/kit/registry.json)
- [Button implementation](https://github.com/n3wth/n3wth/blob/main/apps/kit/registry/new-york/button/button.tsx)
- [Class utility](https://github.com/n3wth/n3wth/blob/main/apps/kit/registry/lib/cn/cn.ts)
- [Alias configuration](https://github.com/n3wth/n3wth/blob/main/apps/kit/components.json)
- [Kit package metadata](https://github.com/n3wth/n3wth/blob/main/apps/kit/package.json)