# scn-stack — Full Documentation

> Scaffold a complete shadcn component registry with documentation in minutes.

Website: https://scnstack.sh
GitHub: https://github.com/jal-co/scn-stack
npm: https://www.npmjs.com/package/create-scn-stack

---

## Quick Start

> Create your first shadcn registry in minutes.
> Source: https://scnstack.sh/docs

## Get Started

### Prerequisites

- **Node.js 18+** — [Download from nodejs.org](https://nodejs.org/)
- **Git** — [Download from git-scm.com](https://git-scm.com/)

### Create a Registry

```bash
npx create-scn-stack
```

Follow the interactive prompts to configure your registry. Or skip prompts entirely:

```bash
npx create-scn-stack my-ui --yes
```

Want to share items straight from a public repo with **no build, no host, and no server**? Scaffold a [GitHub source registry](/docs/distribution/github-registries) instead — users install with `npx shadcn add <owner>/<repo>/<item>`:

```bash
npx create-scn-stack my-toolkit --github acme/toolkit
```

The CLI will:

1. Ask you for a registry name, framework, docs engine, and more
2. Generate all project files with the registry `include` pattern
3. Create starter components with live preview demos
4. Set up theme scaffolding and v0 integration
5. Generate `llms.txt` and `.scn-stack.json` config
6. Install dependencies and the shadcn AI skill
7. Initialize a git repository

### Add to an Existing Project

Already have a project? Add a registry to it:

```bash
npx create-scn-stack init
```

This detects your framework, creates `registry.json`, `components.json`, adds a `registry:build` script, and optionally scaffolds documentation. See [init command](/docs/cli/options#init) for details.

### Start Development

```bash
cd my-ui
pnpm dev
```

Your registry is now running at `http://localhost:3000` with:
- A **landing page** with install instructions
- **Documentation** with live component previews
- **Registry endpoints** at `/r/registry.json`

### Add Components, Hooks & Blocks

```bash
npx create-scn-stack add-component input -d "A text input component."
npx create-scn-stack add-hook use-toggle -d "A toggle state hook."
npx create-scn-stack add-block login-form -d "A login form block."
```

Each command creates the source file, adds it to `registry.json`, generates a doc page, and updates navigation — all in one command.

### Build & Validate

```bash
npx shadcn registry validate
pnpm registry:build
```

This validates your registry schema and generates static JSON files in `public/r/`.

### Deploy

Deploy to Vercel, Netlify, or any platform that supports your framework. Your registry is a standard web app — no special hosting required.

Once deployed, anyone can install your components:

```bash
npx shadcn add @my-ui/button
```

## What is a shadcn Registry?

A [shadcn registry](https://ui.shadcn.com/docs/registry) is a way to distribute components, hooks, blocks, and other code that users can install with the `shadcn` CLI.

Unlike npm packages, registry components are **copied into the user's project** as source code they own and can customize. It's the same pattern that `shadcn/ui` itself uses.

### Why Build a Registry?

- **Design systems** — distribute your company's component library
- **Open source** — share themed or specialized components with the community
- **Internal tools** — standardize UI across projects in your org
- **Commercial** — sell premium component collections

## Next Steps

- [CLI Options](/docs/cli/options) — all prompts, flags, and commands
- [Project Structure](/docs/project-structure) — what gets generated
- [Frameworks](/docs/frameworks/nextjs) — framework-specific details

---

## Project Structure

> What gets generated and where everything goes.
> Source: https://scnstack.sh/docs/project-structure

## Overview

After running `npx create-scn-stack`, you'll get a fully configured project. Here's the structure for a **Next.js + Fumadocs** setup with essentials:

## Key Files

### registry.json (Root)

The root registry uses the `include` pattern to compose from per-directory files:

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "my-ui",
  "homepage": "https://my-ui.com",
  "include": [
    "registry/new-york/ui/registry.json",
    "registry/new-york/themes/registry.json"
  ]
}
```

### registry/\<style\>/ui/registry.json

Per-directory registry defining each component. File paths are relative to this file:

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "items": [
    {
      "name": "button",
      "type": "registry:ui",
      "title": "Button",
      "description": "A button component with multiple variants.",
      "dependencies": ["class-variance-authority"],
      "files": [
        { "path": "button.tsx", "type": "registry:ui" }
      ]
    }
  ]
}
```

### components.json

The shadcn configuration for your project. Includes your style, aliases, and namespace.

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide",
  "registries": {
    "@my-ui": "https://my-ui.com/r/{name}.json"
  }
}
```

### .scn-stack.json

Stores your project's scaffolding configuration for repeatable operations. Used by `add-component`, `add-hook`, and `add-block` commands.

```json
{
  "$schema": "https://scnstack.sh/schema/scn-stack.json",
  "name": "my-ui",
  "style": "new-york",
  "homepage": "https://my-ui.com",
  "framework": "nextjs",
  "docsEngine": "fumadocs",
  "baseLibrary": "radix",
  "namespace": "@my-ui",
  "features": {
    "skills": true
  }
}
```

### Component Previews

Each component doc page includes a live preview using `ComponentPreview` and demo files that import directly from the registry source:

```tsx
import { ComponentPreview } from "@/components/component-preview"
import { ButtonDemo } from "@/components/examples/button-demo"

```

For iframe-based previews (useful for isolated rendering), use the `PreviewFrame` component:

```tsx
import { PreviewFrame } from "@/components/preview-frame"

<PreviewFrame name="button" height={300} />
```

This renders the component at `/preview/button` in an iframe. Add your demos to the `PREVIEWS` map in `app/preview/[name]/page.tsx`.

### v0 Integration

The generated project includes an "Open in v0" button component and a URL helper:

```tsx
import { OpenInV0 } from "@/components/open-in-v0"

<OpenInV0 name="button" />
```

This links to [v0.dev](https://v0.dev) with a pre-filled prompt referencing your registry component.

### Theme

A custom theme is scaffolded in `registry/<style>/themes/` with CSS custom properties. Users can install it with:

```bash
npx shadcn add @my-ui/theme-my-ui
```

Edit the CSS file to customize your registry's visual identity.

### llms.txt

An auto-generated `llms.txt` gives LLMs context about your registry. For Next.js projects, this is a route handler at `/llms.txt`. For other frameworks, it's a static file in `public/`.

### AI Skills

If enabled, the project includes an `.agents/skills/registry/SKILL.md` that teaches AI assistants (Claude, Cursor, Copilot) how to work with your specific registry — adding components, hooks, blocks, writing docs, building, and following conventions.

### public/r/ (Generated)

Static JSON files generated by `shadcn build`. This is what the shadcn CLI fetches when users install your components. **Don't edit these directly** — they're generated from `registry.json` and your source files.

## Adding to the Registry

### Components

```bash
npx create-scn-stack add-component input -d "A text input component."
```

Creates `registry/<style>/ui/<name>.tsx`, adds to registry, generates a doc page, and updates navigation.

### Hooks

```bash
npx create-scn-stack add-hook use-toggle -d "A toggle state hook."
```

Creates `registry/<style>/hooks/<name>.ts`, creates or updates the hooks registry, and generates a doc page.

### Blocks

```bash
npx create-scn-stack add-block login-form -d "A login form block."
```

Creates `registry/<style>/blocks/<name>.tsx`, creates or updates the blocks registry, and generates a doc page.

### Manual

1. Create your file in the appropriate `registry/<style>/` directory
2. Add the item to the corresponding `registry.json`
3. Run `pnpm registry:build`
4. Add a documentation page

## Validate & Build

```bash
npx shadcn registry validate
pnpm registry:build
```

## Scripts

| Script | Description |
|--------|-------------|
| `dev` | Start development server |
| `build` | Build for production (includes registry build) |
| `registry:build` | Generate static registry JSON files |
| `start` | Start production server |
| `lint` | Run ESLint |

---

## Options Reference

> All CLI prompts, flags, and commands.
> Source: https://scnstack.sh/docs/cli/options

## Commands

| Command | Description |
|---------|-------------|
| `npx create-scn-stack` | Scaffold a new registry project |
| `npx create-scn-stack init` | [Add a registry to an existing project](/docs/cli/init) |
| `npx create-scn-stack add-component <name>` | Add a component to an existing registry |
| `npx create-scn-stack add-hook <name>` | Add a hook to an existing registry |
| `npx create-scn-stack add-block <name>` | Add a block to an existing registry |
| `npx create-scn-stack add-theme <name>` | Add a theme to an existing registry |
| `npx create-scn-stack add-file <name>` | Add an arbitrary file item (conventions, CI, agent instructions) |
| `npx create-scn-stack remove <name>` | Remove an item (source + registry + docs) |
| `npx create-scn-stack list` | List everything in the registry |
| `npx create-scn-stack build` | Build the registry output (`public/r/`) |
| `npx create-scn-stack eject` | Inline `shadcn/tailwind.css`, drop the `shadcn` dependency |

## Prompts

When you run `npx create-scn-stack`, you'll be guided through these options:

| Prompt | Description | Default |
|--------|-------------|---------|
| **Registry name** | Identifier for your registry (e.g., `my-ui`) | `my-ui` |
| **Project location** | Folder to create the registry in | `./<registry-name>` |
| **Distribution** | [Hosted](/docs/distribution/hosted) (build + host) or [GitHub source registry](/docs/distribution/github-registries) | `Hosted` |
| **GitHub repo** | `owner/repo` slug (GitHub target only, optional) | `<owner>/<name>` |
| **Style** | shadcn/ui style variant | `New York` |
| **Homepage** | URL where the registry will be hosted | `https://<name>.com` |
| **Framework** | Web framework for the project (hosted only) | `Next.js` |
| **Documentation** | Docs engine to include | `Fumadocs` |
| **Starter components** | Pre-built example components | `Button, Card, Badge` |
| **Namespace** | Registry namespace for `@name/component` installs | `@<name>` |
| **Package manager** | Package manager to use | Auto-detected |
| **AI skills** | Install shadcn skill + registry skill | `Yes` |

## Flags

All prompts can be pre-filled via flags. Use `--yes` to skip prompts entirely.

```bash
npx create-scn-stack my-ui --yes
npx create-scn-stack my-ui --framework nextjs --docs fumadocs --pm pnpm
npx create-scn-stack my-ui --yes --no-skills
```

| Flag | Values |
|------|--------|
| `--name <name>` | Registry name |
| `--directory <path>` | Project location |
| `--style <style>` | `new-york` \| `default` |
| `--homepage <url>` | Registry homepage URL |
| `--target <target>` | `hosted` \| `github` (default: `hosted`) |
| `--github [owner/repo]` | Shorthand for `--target github` — see [GitHub registries](/docs/distribution/github-registries) |
| `--github-slug <slug>` | `owner/repo` for GitHub source registries |
| `--framework <fw>` | `nextjs` \| `vite` \| `react-router` \| `tanstack-start` |
| `--docs <engine>` | `fumadocs` \| `mintlify` \| `starlight` \| `none` |
| `--components <set>` | `essentials` \| `minimal` \| `none` |
| `--namespace <ns>` | Namespace (e.g., `@my-ui`) |
| `--pm <pm>` | `pnpm` \| `npm` \| `yarn` \| `bun` |
| `--skills` | Include AI skills |
| `--no-skills` | Skip AI skills |
| `-y, --yes` | Skip all prompts, use defaults |
| `-h, --help` | Show help |

## add-component

Add a component to an existing registry project:

```bash
npx create-scn-stack add-component input
npx create-scn-stack add-component dialog -d "A modal dialog component."
```

This creates:
- Component source in `registry/<style>/ui/<name>.tsx`
- Entry in `registry/<style>/ui/registry.json` (detects include pattern)
- Doc page in `content/docs/components/<name>.mdx`
- Updates `meta.json` navigation

| Flag | Description |
|------|-------------|
| `--description, -d` | Component description |

## add-hook

Add a hook to an existing registry project:

```bash
npx create-scn-stack add-hook use-toggle
npx create-scn-stack add-hook use-media-query -d "A media query hook."
```

This creates:
- Hook source in `registry/<style>/hooks/<name>.ts`
- A `registry/<style>/hooks/registry.json` (created if needed)
- Updates root `registry.json` include array to reference hooks registry
- Doc page in `content/docs/hooks/<name>.mdx`
- Updates `meta.json` navigation

Hook names must start with `use-`.

| Flag | Description |
|------|-------------|
| `--description, -d` | Hook description |

## add-block

Add a block to an existing registry project:

```bash
npx create-scn-stack add-block login-form
npx create-scn-stack add-block dashboard-header -d "A dashboard header block."
```

This creates:
- Block source in `registry/<style>/blocks/<name>.tsx`
- A `registry/<style>/blocks/registry.json` (created if needed)
- Updates root `registry.json` include array to reference blocks registry
- Doc page in `content/docs/blocks/<name>.mdx`
- Updates `meta.json` navigation

| Flag | Description |
|------|-------------|
| `--description, -d` | Block description |

## add-theme

Add a distributable theme to an existing registry project:

```bash
npx create-scn-stack add-theme midnight
npx create-scn-stack add-theme sunset -d "A warm, high-contrast theme."
```

This creates:
- Theme CSS in `registry/<style>/themes/<name>.css` (light + dark tokens)
- A `registry/<style>/themes/registry.json` (created if needed)
- Updates root `registry.json` include array to reference the themes registry
- Doc page in `content/docs/themes/<name>.mdx`
- Updates `meta.json` navigation

Themes are registered as `theme-<name>` (matching shadcn convention), so a
theme named `midnight` installs with `npx shadcn add @you/theme-midnight`.

| Flag | Description |
|------|-------------|
| `--description, -d` | Theme description |

## remove

Remove an item from an existing registry project. This is the full reverse
of any `add-*` command:

```bash
npx create-scn-stack remove button
npx create-scn-stack remove use-toggle --yes
```

It finds the item across the root registry and any `include`d per-directory
registries, then:
- Deletes the item's source file(s)
- Removes the entry from the relevant `registry.json`
- Deletes the matching doc page and prunes it from `meta.json`

By default it prints exactly what will be deleted and asks for confirmation.
Pass `--yes` to skip the prompt (useful in scripts).

| Flag | Description |
|------|-------------|
| `-y, --yes` | Skip the confirmation prompt |

## list

List everything registered in the current project, grouped by kind:

```bash
npx create-scn-stack list
npx create-scn-stack list --type hook
npx create-scn-stack list --json
```

`--json` prints a machine-readable array (name, type, title, description)
and suppresses all branding — ideal for piping into other tools.

| Flag | Values |
|------|--------|
| `--type, -t <type>` | `ui` \| `hook` \| `block` \| `theme` |
| `--json` | Output machine-readable JSON |

## build

Build the registry output to `public/r/`:

```bash
npx create-scn-stack build
```

A convenience passthrough that runs your project's `registry:build` script
(or `shadcn build` directly if no script is defined). The package manager is
detected from the project's lockfile.

## Framework Options

| Framework | Description |
|-----------|-------------|
| **Next.js** | App Router with Tailwind v4. Recommended for most registries. |
| **Vite** | React + Vite with Tailwind v4. Lightweight, fast builds. |
| **React Router** | React Router v7 with SSR support. |
| **TanStack Start** | TanStack Start with file-based routing. |

## Docs Engine Options

| Engine | Description |
|--------|-------------|
| **Fumadocs** | Standard for shadcn registries. Full docs with MDX, search, dark mode. Requires Next.js. |
| **Mintlify** | Hosted docs platform. Works with any framework. |
| **Starlight** | Astro-based docs. Separate `docs/` directory. Works with any framework. |
| **None** | Registry only, no documentation site. |

## Style Options

| Style | Description |
|-------|-------------|
| **New York** | Default shadcn/ui style. Smaller, compact components. |
| **Default** | Original shadcn/ui style. Slightly larger components. |

## Starter Components

| Set | Components | Includes |
|-----|------------|----------|
| **Essentials** | Button, Card, Badge | Source files, registry entries, doc pages with live previews |
| **Minimal** | Button only | Source file, registry entry, doc page with preview |
| **None** | Empty registry | Just the scaffold, add your own |

## AI Skills

| Skill | What it does |
|-------|-------------|
| **shadcn skill** | Installs the [official shadcn skill](https://ui.shadcn.com/docs/skills) via `skills add shadcn/ui`. Gives AI assistants knowledge of shadcn components, CLI, theming, and registry authoring. |
| **Registry skill** | Generates `.agents/skills/registry/SKILL.md` — teaches AI how to add components, hooks, blocks, write docs, update registry.json, and follow conventions for your specific project. |

---

## Using the Prompts

> Walkthrough of the interactive CLI experience.
> Source: https://scnstack.sh/docs/cli/prompts

## Running the CLI

```bash
npx create-scn-stack
```

The CLI guides you through every decision with interactive prompts. Here's what each one does:

### Registry Name

```
◆  Registry name
│  my-ui
```

This becomes your registry's identifier — used in `registry.json`, the namespace (`@my-ui`), and throughout the generated code. Must be lowercase with hyphens only.

### Project Location

```
◆  Project location
│  ./my-ui
```

The folder where your project will be created. Optional — press Enter to accept the default of `./<registry-name>`, or use `.` to scaffold in the current directory. The path must be inside your current directory.

### Distribution

```
◆  How should the registry be distributed?
│  ● Hosted (framework app + build + host)
│  ○ GitHub source registry (no build, no host)
```

Choose how users install your items. **Hosted** scaffolds a framework app, a
build step, and a homepage URL. **GitHub** produces a minimal repo that *is*
the registry — users install with `npx shadcn add <owner>/<repo>/<item>` and
there's no build or server. Picking GitHub asks for an `owner/repo` slug
(optional — leave it blank to scaffold with a `<owner>/<name>` placeholder you
can fill in later) and skips the framework, docs, namespace, and monorepo
prompts. See [GitHub Registries](/docs/distribution/github-registries).

### Style

```
◆  Style
│  ● New York (recommended)
│  ○ Default
```

The [shadcn/ui style variant](https://ui.shadcn.com/docs/theming). Determines the component file paths (`registry/new-york/ui/` vs `registry/default/ui/`) and the style field in `components.json`.

### Homepage

```
◆  Homepage
│  https://my-ui.com
```

The URL where your registry will be deployed. Used in `registry.json` homepage field and in namespace URL templates. You can change this later.

### Framework

```
◆  Framework
│  ● Next.js (recommended)
│  ○ Vite (React)
│  ○ React Router
│  ○ TanStack Start
```

The web framework for your project. **Next.js** is recommended — it's what the official registry template uses, and Fumadocs requires it.

### Documentation

```
◆  Documentation
│  ● Fumadocs (recommended)
│  ○ Mintlify
│  ○ Starlight
│  ○ None
```

Whether to include a documentation site. **Fumadocs** is the standard for shadcn registries (used by 8bitcn, and many others). **Mintlify** is a hosted platform that works with any framework. If you choose a non-Next.js framework with Fumadocs selected, Starlight will be used instead.

### Starter Components

```
◆  Starter components
│  ● Button, Card, Badge (essentials)
│  ○ Button only (minimal)
│  ○ None (empty registry)
```

Pre-built components to include as examples. Each comes with a source file, registry entry, and documentation page.

### Namespace

```
◆  Add a namespace? Yes
◆  Namespace
│  @my-ui
```

Enables `@my-ui/button` style installs. Sets up the registries field in `components.json` with your homepage URL template.

### Package Manager

```
◆  Package manager
│  ● pnpm
│  ○ npm
│  ○ yarn
│  ○ bun
```

Auto-detected from how you ran the CLI. All generated scripts use the selected package manager.

---

## Init Prompts

When you run `npx create-scn-stack init` in an existing project, you'll see a shorter set of prompts:

```
◆  Detected framework: Next.js
◆  Registry name
│  my-app
◆  Style
│  ● New York (recommended)
│  ○ Default
◆  Homepage URL
│  https://my-app.com
◆  Add a namespace? Yes
◆  Namespace
│  @my-app
◆  Add documentation pages? Yes
```

The init command auto-detects your framework from `package.json` and existing `components.json`, so it only asks what it needs.

---

## Add Command Prompts

The `add-component`, `add-hook`, and `add-block` commands prompt for a name and description if not provided via arguments:

```
◆  Component name
│  input
◆  Description
│  A text input component.
```

Skip the prompts by passing arguments directly:

```bash
npx create-scn-stack add-component input -d "A text input component."
npx create-scn-stack add-hook use-toggle -d "A toggle state hook."
npx create-scn-stack add-block login-form -d "A login form block."
```

---

## Next.js

> Using scn-stack with Next.js — the recommended framework.
> Source: https://scnstack.sh/docs/frameworks/nextjs

## Overview

Next.js is the **recommended framework** for scn-stack. It's what the official [shadcn registry template](https://github.com/shadcn-ui/registry-template) uses, and it's required for Fumadocs.

## What You Get

- **Next.js 16** with App Router and Turbopack
- **Tailwind v4** with `@tailwindcss/postcss`
- **shadcn v3** registry build system
- **Fumadocs v16** (if selected) with full docs site
- **Geist** font family

## Registry Serving

Your registry is served as **static files** via `public/r/`. When you run `pnpm registry:build`, the shadcn CLI reads your `registry.json` and generates JSON files:

Next.js serves everything in `public/` automatically — no route handlers needed.

## Development

```bash
pnpm dev              # Start with Turbopack
pnpm build            # Production build (includes registry build)
pnpm registry:build   # Build registry JSON only
```

## Deployment

Deploy to any platform that supports Next.js:

- **Vercel** — zero config
- **Netlify** — `netlify deploy`
- **Cloudflare Pages** — via `@cloudflare/next-on-pages`
- **Self-hosted** — `pnpm build && pnpm start`

---

## Vite

> Using scn-stack with Vite for lightweight React projects.
> Source: https://scnstack.sh/docs/frameworks/vite

## Overview

Vite is a great choice for lightweight registry projects that don't need SSR. Fast builds, simple configuration.

## What You Get

- **Vite 6** with React plugin
- **Tailwind v4** with `@tailwindcss/vite`
- **React Router DOM** for client-side routing
- **shadcn v3** registry build system

## Registry Serving

Same static file approach as Next.js. Run `pnpm registry:build` to generate `public/r/*.json` files. Vite serves the `public/` directory in both dev and production.

## Documentation

Since Fumadocs requires Next.js, choosing Vite with docs will use **Starlight** instead — generating a separate Astro docs site in a `docs/` subdirectory.

## Development

```bash
pnpm dev             # Start Vite dev server
pnpm build           # Production build
pnpm registry:build  # Build registry JSON
```

---

## React Router

> Using scn-stack with React Router v7.
> Source: https://scnstack.sh/docs/frameworks/react-router

## Overview

React Router v7 with SSR support. Good for projects that want server rendering without the full Next.js ecosystem.

## What You Get

- **React Router v7** with file-based routing
- **Vite 6** as the build tool
- **Tailwind v4** with `@tailwindcss/vite`
- **shadcn v3** registry build system

## Documentation

Uses **Starlight** for docs (separate `docs/` directory), since Fumadocs requires Next.js.

## Development

```bash
pnpm dev             # Start dev server
pnpm build           # Production build
pnpm registry:build  # Build registry JSON
pnpm start           # Start production server
```

---

## TanStack Start

> Using scn-stack with TanStack Start.
> Source: https://scnstack.sh/docs/frameworks/tanstack-start

## Overview

TanStack Start with Vinxi and file-based routing. For projects in the TanStack ecosystem.

## What You Get

- **TanStack Start** with TanStack Router
- **Vinxi** as the server framework
- **Tailwind v4** with `@tailwindcss/vite`
- **shadcn v3** registry build system

## Documentation

Uses **Starlight** for docs (separate `docs/` directory), since Fumadocs requires Next.js.

## Development

```bash
pnpm dev             # Start Vinxi dev server
pnpm build           # Production build
pnpm registry:build  # Build registry JSON
pnpm start           # Start production server
```

---

## Fumadocs

> The recommended docs engine for shadcn registries.
> Source: https://scnstack.sh/docs/docs-engines/fumadocs

## Overview

[Fumadocs](https://fumadocs.vercel.app) is a docs framework built on React. It's the **de facto standard** for shadcn component registries — used by [8bitcn](https://8bitcn.com) and many others.

## Requirements

Fumadocs requires **Next.js**. If you select a different framework, the CLI will suggest Starlight instead.

## What You Get

- Full docs site at `/docs` integrated into your Next.js app
- MDX content in `content/docs/` with frontmatter
- Sidebar navigation via `meta.json` files
- Dark mode, search, and table of contents
- Auto-generated component documentation pages

## File Structure

## Adding a Doc Page

Create a new `.mdx` file in `content/docs/`:

```mdx
---
title: My Component
description: A description of your component.
---

## Installation

\`\`\`bash
npx shadcn add @my-ui/my-component
\`\`\`

## Usage

\`\`\`tsx
import { MyComponent } from "@/components/ui/my-component"
\`\`\`
```

Add it to the appropriate `meta.json` to control navigation order.

## Customization

Fumadocs is highly customizable. See the [Fumadocs documentation](https://fumadocs.vercel.app/docs) for:

- Custom layouts and themes
- Search configuration
- OpenAPI integration
- Internationalization

---

## Mintlify

> Hosted documentation platform — works with any framework.
> Source: https://scnstack.sh/docs/docs-engines/mintlify

## Overview

[Mintlify](https://mintlify.com) is a hosted documentation platform used by Stripe, Twilio, Resend, and hundreds of developer tools companies. It's the simplest docs option — just MDX content + a config file, no framework code.

## What You Get

Mintlify generates a `docs/` directory in your project with:

## How It Works

Unlike Fumadocs and Starlight, Mintlify is a **hosted service** — your docs are rendered by Mintlify's platform, not your own server. You push MDX files to your repo, and Mintlify auto-deploys them.

1. Sign up at [mintlify.com/start](https://mintlify.com/start)
2. Connect your GitHub repo
3. Point Mintlify at the `docs/` directory
4. Push changes → docs auto-deploy to `yourproject.mintlify.app`

## When to Use Mintlify

- You want the **fastest setup** — zero framework code, just content
- You want **hosted deployment** — no Vercel/Netlify needed for docs
- You're using a **non-Next.js framework** and want beautiful docs
- You want built-in **search, analytics, and API reference**
- Your team prefers a **web editor** over code

## Configuration

The `mint.json` file controls navigation, branding, and layout:

```json
{
  "$schema": "https://mintlify.com/schema.json",
  "name": "my-ui",
  "colors": {
    "primary": "#171717",
    "light": "#FAFAFA",
    "dark": "#171717"
  },
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction", "installation"]
    },
    {
      "group": "Components",
      "pages": ["components/button", "components/card"]
    }
  ]
}
```

## Local Preview

```bash
npm i -g mint
cd docs
mint dev
```

## Adding a Doc Page

Create a new `.mdx` file in `docs/components/`:

```mdx
---
title: My Component
description: A description of your component.
---

## Installation

\`\`\`bash
npx shadcn add @my-ui/my-component
\`\`\`
```

Add it to the `navigation` array in `mint.json`.

## Comparison

| Feature | Fumadocs | Mintlify | Starlight |
|---------|----------|----------|-----------|
| Self-hosted | ✅ | ❌ (hosted) | ✅ |
| Requires Next.js | ✅ | ❌ | ❌ |
| Component previews | ✅ (inline) | Via iframe | Via iframe |
| Search | Plugin | Built-in | Built-in |
| Web editor | ❌ | ✅ | ❌ |
| API reference | ❌ | ✅ | ❌ |
| Free tier | ✅ (OSS) | ✅ (limited) | ✅ (OSS) |

---

## Starlight

> Astro-based documentation for non-Next.js projects.
> Source: https://scnstack.sh/docs/docs-engines/starlight

## Overview

[Starlight](https://starlight.astro.build) is a documentation framework built on Astro. It's used when you choose a non-Next.js framework, or when you prefer Astro's approach.

## What You Get

Starlight generates a **separate docs site** in a `docs/` subdirectory of your project:

## Development

The docs site runs separately from your main app:

```bash
cd docs
pnpm dev
```

## Deployment

Deploy the docs site separately, or as a subdirectory of your main deploy. Many teams host docs on a subdomain like `docs.my-ui.com`.

## When to Use Starlight

- You're using Vite, React Router, or TanStack Start
- You prefer Astro's static-first approach
- You want docs on a separate domain/subdomain
- You don't need tight integration with your main app

---