Component Registry

Shipkit features are available as installable shadcn registry blocks. Add auth, blog, docs, CMS, or FAQ to any Next.js project with a single command.

Quick Start

1. Add the Shipkit registry

In your project's components.json, add the Shipkit registry:

{
  "registries": {
    "@shipkit": "https://shipkit.io/r/{name}.json"
  }
}

2. Install a block

npx shadcn add @shipkit/faq
npx shadcn add @shipkit/blog
npx shadcn add @shipkit/docs
npx shadcn add @shipkit/auth
npx shadcn add @shipkit/builder-io
npx shadcn add @shipkit/cms-pages

Or install directly via URL:

npx shadcn add https://shipkit.io/r/faq.json

Available Blocks

Feature Blocks

Block	Files	Description
`faq`	3	Accordion FAQ page with static content and optional Payload CMS integration
`docs`	12	Full documentation system — sidebar, search, MDX rendering
`blog`	24	Blog with author profiles, categories, feed-style timeline, sidebar
`builder-io`	11	Builder.io visual page builder — components, config, standalone route
`cms-pages`	11	Shared Payload + Builder.io catch-all route with automatic fallback
`auth`	41	NextAuth.js v5 — OAuth, credentials, magic link, guest access, RBAC

Shared Infrastructure

These are installed automatically as dependencies of the feature blocks above.

Item	Type	Description
`cn`	`registry:lib`	Tailwind class merging utility (`clsx` + `tailwind-merge`)
`routes-config`	`registry:lib`	Centralized route definitions
`features-config`	`registry:lib`	Build-time feature flag detection from env vars

UI Components

Standalone UI components, also installable individually:

Component	Description
`marquee`	Infinite scrolling marquee (horizontal/vertical)
`border-beam`	Animated beam tracing a container border
`retro-grid`	Perspective grid background
`shimmer-button`	Button with rotating shimmer effect
`dock`	macOS-style dock with magnification
`use-copy-to-clipboard`	Clipboard hook with timeout reset
`use-mobile`	Mobile viewport detection hook

Block Details

FAQ

The simplest block — good for validating your registry setup.

npx shadcn add @shipkit/faq

Installs to:

app/(app)/faq/page.tsx — Server component with accordion layout
app/(app)/faq/loading.tsx — Loading skeleton
content/faq/faq-content.tsx — Static FAQ content (8 questions)

Dependencies: accordion (shadcn), cn

The page loads FAQs from Payload CMS when available, falling back to the static content file. Edit faq-content.tsx to customize questions.

Docs

Full documentation system powered by MDX.

npx shadcn add @shipkit/docs

Installs to:

app/docs/ — Layout, page, loading, not-found, styles
app/docs/_components/ — Sidebar, header, search dialog
app/api/docs/search/ — Search API route (optional AI-powered answers)
lib/docs.ts — Doc utilities (slug resolution, navigation, search)
hooks/use-docs-search.ts — Client-side search hook with debouncing
server/services/docs-search.ts — Server-side search service

Dependencies: next-mdx-remote, remark-gfm, gray-matter, zod

Place .mdx files in a docs/ directory at your project root. The system auto-discovers files and builds sidebar navigation from the directory structure.

Blog

MDX-powered blog with author profiles and feed-style timeline.

npx shadcn add @shipkit/blog

Installs to:

app/blog/ — Listing, post pages, categories, author pages
components/modules/blog/ — 10 components (hero, post, authors, TOC, skeletons)
components/layouts/blog-sidebar.tsx — Sticky sidebar with search
lib/blog.ts — Blog utilities (post loading, category extraction)
config/blog-authors.ts — Author configuration
config/nextjs/with-blog.ts — Next.js config wrapper
styles/blog.css — Timeline and sidebar styles

Dependencies: gray-matter, next-mdx-remote, remark-gfm, lucide-react

Place .mdx posts in src/content/blog/. Add withBlog() to your next.config.ts to auto-detect blog content and set the NEXT_PUBLIC_HAS_BLOG flag.

Builder.io

Visual page builder for no-code content editing.

npx shadcn add @shipkit/builder-io

Installs to:

app/builder.io/[...slug]/page.tsx — Standalone catch-all route
lib/builder-io/builder-io.tsx — RenderBuilderContent component
builder-registry.ts — Component registration (Hero, Stats, CTA)
components/modules/builder/ — 5 Builder.io block components
config/nextjs/with-builder.ts — Next.js config wrapper
styles/builder-io.css — Builder.io overrides

Dependencies: @builder.io/react, @builder.io/sdk, @builder.io/dev-tools

Setup: Sign up at builder.io, set BUILDER_API_KEY in .env. Wrap your Next.js config with withBuilderConfig().

CMS Pages

Shared catch-all route for Payload CMS and Builder.io coexistence.

npx shadcn add @shipkit/cms-pages

Installs to:

app/(cms)/[...slug]/page.tsx — Unified catch-all handler
app/(cms)/layout.tsx — Conditional Payload layout (tree-shakes when disabled)
app/(cms)/payload-root-layout.tsx — Payload CSS/config loader
app/(cms)/payload-blocks.tsx — Block renderer (Hero, Content, Features, Testimonials)
app/(cms)/ — 4 Payload block components
types/blocks.ts — Block type definitions

How routing works:

Request to /<any-path>
  -> (cms)/[...slug] catches it
  -> Checks Payload CMS database for matching page
  -> If not found, falls back to Builder.io API
  -> If neither has content, returns 404

Payload is checked first (higher priority). Both CMS systems can be independently enabled/disabled via feature flags. Installing this block automatically pulls in the builder-io block.

Auth

Full authentication system with multi-provider support.

npx shadcn add @shipkit/auth

Installs to:

app/(authentication)/ — Sign-in, sign-up, forgot/reset password, error pages
app/(authentication)/_components/ — Auth form, credentials, magic link, guest, OAuth buttons
app/api/auth/[...nextauth]/route.ts — NextAuth API route
server/auth.ts — NextAuth configuration with Drizzle adapter
server/auth-js/ — Provider configs, utilities
server/actions/auth.ts — Server actions (sign in, sign up, password reset)
server/services/ — Auth service, user service
server/db/schema.ts — Drizzle schema (users, accounts, sessions, verification tokens)
hooks/ — Auth redirect hooks
lib/schemas/ — Zod validation schemas
types/ — User types, NextAuth type augmentation
components/buttons/ — Sign-in button, GitHub OAuth button

Dependencies: next-auth@5, @auth/drizzle-adapter, bcryptjs, zod, zsa

Setup:

Run npx auth secret to generate AUTH_SECRET
Set DATABASE_URL for PostgreSQL
Run Drizzle migrations: npx drizzle-kit generate && npx drizzle-kit migrate
Configure at least one provider (e.g., AUTH_GITHUB_ID + AUTH_GITHUB_SECRET)
Or enable guest access: ENABLE_AUTH_GUEST=true

Route Groups

All blocks install into the (app) route group by default. This is required for compatibility with Payload CMS, which uses a separate (cms) route group.

app/
├── (app)/           <- Feature blocks install here
│   ├── faq/
│   ├── docs/
│   ├── blog/
│   ├── builder.io/
│   └── (authentication)/
├── (cms)/       <- CMS pages block installs here
│   ├── [...slug]/   <- Shared Payload + Builder.io catch-all
│   ├── cms/         <- Payload admin panel
│   └── cms-api/     <- Payload REST API
└── layout.tsx

For Maintainers

Source & Build

The registry source is registry.json at the project root. Running npx shadcn build reads this file and generates individual JSON files in public/r/.

# Build registry
bun run build:registry    # or: npx shadcn build

# Output
public/r/
├── registry.json         # Auto-generated index
├── faq.json              # Per-block JSON with embedded file contents
├── auth.json
└── ...

Adding a New Block

Add an entry to registry.json:

{
  "name": "my-block",
  "type": "registry:block",
  "title": "My Block",
  "description": "What it does.",
  "categories": ["shipkit", "my-category"],
  "dependencies": ["some-npm-package"],
  "registryDependencies": ["cn", "button"],
  "files": [
    {
      "path": "src/app/(app)/my-route/page.tsx",
      "type": "registry:page",
      "target": "~/app/(app)/my-route/page.tsx"
    }
  ],
  "docs": "Setup instructions shown after installation."
}

Run bun run build:registry to generate the output files.
Test locally (see Local Testing below).

Local Testing

To test registry blocks locally before deploying:

Option A: Use the dev server

# Terminal 1
bun dev

# Terminal 2
npx shadcn add http://localhost:3000/r/faq.json

Option B: Quick static server (no full Next.js build needed)

# Terminal 1
npx serve public/r -p 5555

# Terminal 2
npx shadcn add http://localhost:5555/faq.json

Resolving custom registry dependencies locally:

Direct URL installs (http://localhost:.../faq.json) will fail if the block has registryDependencies that reference custom items like cn or routes-config — shadcn tries to resolve those from its default registry at shadcn.com.

To fix this, add a local Shipkit registry to your test project's components.json:

{
  "registries": {
    "@shipkit": "http://localhost:3000/r/{name}.json"
  }
}

Then install via the registry prefix:

npx shadcn add @shipkit/faq

This resolves all internal deps (cn, routes-config, etc.) through the local server. Standard shadcn deps (accordion, button, etc.) still resolve from shadcn.com as normal.

Tip: If you just want to verify file installation and the dependencies already exist in the project, the direct URL approach works fine — dependency resolution is only needed for fresh consumer projects.

File Entry Types

Type	Use for
`registry:page`	Route pages (`page.tsx`)
`registry:component`	React components, layouts, loading states
`registry:hook`	React hooks
`registry:lib`	Utilities, configs, server code, types, API routes
`registry:style`	CSS files

Target Paths

~ resolves to the project root (relative to components.json)
Always include (app) for routes: ~/app/(app)/my-route/page.tsx
Non-route files keep their path: ~/lib/my-util.ts, ~/hooks/my-hook.ts
path is the source location in Shipkit, target is where it installs in the consumer project

Registry Dependencies

Internal deps (defined in the same registry): cn, routes-config, features-config
shadcn deps (resolved from shadcn.com): accordion, button, card, input, etc.
Consumer projects resolve internal deps by adding the Shipkit registry to their components.json

Component Registry

Shipkit features are available as installable shadcn registry blocks. Add auth, blog, docs, CMS, or FAQ to any Next.js project with a single command.

Quick Start

1. Add the Shipkit registry

In your project's components.json, add the Shipkit registry:

{
  "registries": {
    "@shipkit": "https://shipkit.io/r/{name}.json"
  }
}

2. Install a block

npx shadcn add @shipkit/faq
npx shadcn add @shipkit/blog
npx shadcn add @shipkit/docs
npx shadcn add @shipkit/auth
npx shadcn add @shipkit/builder-io
npx shadcn add @shipkit/cms-pages

Or install directly via URL:

npx shadcn add https://shipkit.io/r/faq.json

Available Blocks

Feature Blocks

Block	Files	Description
`faq`	3	Accordion FAQ page with static content and optional Payload CMS integration
`docs`	12	Full documentation system — sidebar, search, MDX rendering
`blog`	24	Blog with author profiles, categories, feed-style timeline, sidebar
`builder-io`	11	Builder.io visual page builder — components, config, standalone route
`cms-pages`	11	Shared Payload + Builder.io catch-all route with automatic fallback
`auth`	41	NextAuth.js v5 — OAuth, credentials, magic link, guest access, RBAC

Shared Infrastructure

These are installed automatically as dependencies of the feature blocks above.

Item	Type	Description
`cn`	`registry:lib`	Tailwind class merging utility (`clsx` + `tailwind-merge`)
`routes-config`	`registry:lib`	Centralized route definitions
`features-config`	`registry:lib`	Build-time feature flag detection from env vars

UI Components

Standalone UI components, also installable individually:

Component	Description
`marquee`	Infinite scrolling marquee (horizontal/vertical)
`border-beam`	Animated beam tracing a container border
`retro-grid`	Perspective grid background
`shimmer-button`	Button with rotating shimmer effect
`dock`	macOS-style dock with magnification
`use-copy-to-clipboard`	Clipboard hook with timeout reset
`use-mobile`	Mobile viewport detection hook

Block Details

FAQ

The simplest block — good for validating your registry setup.

npx shadcn add @shipkit/faq

Installs to:

app/(app)/faq/page.tsx — Server component with accordion layout
app/(app)/faq/loading.tsx — Loading skeleton
content/faq/faq-content.tsx — Static FAQ content (8 questions)

Dependencies: accordion (shadcn), cn

The page loads FAQs from Payload CMS when available, falling back to the static content file. Edit faq-content.tsx to customize questions.

Docs

Full documentation system powered by MDX.

npx shadcn add @shipkit/docs

Installs to:

app/docs/ — Layout, page, loading, not-found, styles
app/docs/_components/ — Sidebar, header, search dialog
app/api/docs/search/ — Search API route (optional AI-powered answers)
lib/docs.ts — Doc utilities (slug resolution, navigation, search)
hooks/use-docs-search.ts — Client-side search hook with debouncing
server/services/docs-search.ts — Server-side search service

Dependencies: next-mdx-remote, remark-gfm, gray-matter, zod

Place .mdx files in a docs/ directory at your project root. The system auto-discovers files and builds sidebar navigation from the directory structure.

Blog

MDX-powered blog with author profiles and feed-style timeline.

npx shadcn add @shipkit/blog

Installs to:

app/blog/ — Listing, post pages, categories, author pages
components/modules/blog/ — 10 components (hero, post, authors, TOC, skeletons)
components/layouts/blog-sidebar.tsx — Sticky sidebar with search
lib/blog.ts — Blog utilities (post loading, category extraction)
config/blog-authors.ts — Author configuration
config/nextjs/with-blog.ts — Next.js config wrapper
styles/blog.css — Timeline and sidebar styles

Dependencies: gray-matter, next-mdx-remote, remark-gfm, lucide-react

Place .mdx posts in src/content/blog/. Add withBlog() to your next.config.ts to auto-detect blog content and set the NEXT_PUBLIC_HAS_BLOG flag.

Builder.io

Visual page builder for no-code content editing.

npx shadcn add @shipkit/builder-io

Installs to:

app/builder.io/[...slug]/page.tsx — Standalone catch-all route
lib/builder-io/builder-io.tsx — RenderBuilderContent component
builder-registry.ts — Component registration (Hero, Stats, CTA)
components/modules/builder/ — 5 Builder.io block components
config/nextjs/with-builder.ts — Next.js config wrapper
styles/builder-io.css — Builder.io overrides

Dependencies: @builder.io/react, @builder.io/sdk, @builder.io/dev-tools

Setup: Sign up at builder.io, set BUILDER_API_KEY in .env. Wrap your Next.js config with withBuilderConfig().

CMS Pages

Shared catch-all route for Payload CMS and Builder.io coexistence.

npx shadcn add @shipkit/cms-pages

Installs to:

app/(cms)/[...slug]/page.tsx — Unified catch-all handler
app/(cms)/layout.tsx — Conditional Payload layout (tree-shakes when disabled)
app/(cms)/payload-root-layout.tsx — Payload CSS/config loader
app/(cms)/payload-blocks.tsx — Block renderer (Hero, Content, Features, Testimonials)
app/(cms)/ — 4 Payload block components
types/blocks.ts — Block type definitions

How routing works:

Request to /<any-path>
  -> (cms)/[...slug] catches it
  -> Checks Payload CMS database for matching page
  -> If not found, falls back to Builder.io API
  -> If neither has content, returns 404

Payload is checked first (higher priority). Both CMS systems can be independently enabled/disabled via feature flags. Installing this block automatically pulls in the builder-io block.

Auth

Full authentication system with multi-provider support.

npx shadcn add @shipkit/auth

Installs to:

app/(authentication)/ — Sign-in, sign-up, forgot/reset password, error pages
app/(authentication)/_components/ — Auth form, credentials, magic link, guest, OAuth buttons
app/api/auth/[...nextauth]/route.ts — NextAuth API route
server/auth.ts — NextAuth configuration with Drizzle adapter
server/auth-js/ — Provider configs, utilities
server/actions/auth.ts — Server actions (sign in, sign up, password reset)
server/services/ — Auth service, user service
server/db/schema.ts — Drizzle schema (users, accounts, sessions, verification tokens)
hooks/ — Auth redirect hooks
lib/schemas/ — Zod validation schemas
types/ — User types, NextAuth type augmentation
components/buttons/ — Sign-in button, GitHub OAuth button

Dependencies: next-auth@5, @auth/drizzle-adapter, bcryptjs, zod, zsa

Setup:

Run npx auth secret to generate AUTH_SECRET
Set DATABASE_URL for PostgreSQL
Run Drizzle migrations: npx drizzle-kit generate && npx drizzle-kit migrate
Configure at least one provider (e.g., AUTH_GITHUB_ID + AUTH_GITHUB_SECRET)
Or enable guest access: ENABLE_AUTH_GUEST=true

Route Groups

All blocks install into the (app) route group by default. This is required for compatibility with Payload CMS, which uses a separate (cms) route group.

app/
├── (app)/           <- Feature blocks install here
│   ├── faq/
│   ├── docs/
│   ├── blog/
│   ├── builder.io/
│   └── (authentication)/
├── (cms)/       <- CMS pages block installs here
│   ├── [...slug]/   <- Shared Payload + Builder.io catch-all
│   ├── cms/         <- Payload admin panel
│   └── cms-api/     <- Payload REST API
└── layout.tsx

For Maintainers

Source & Build

The registry source is registry.json at the project root. Running npx shadcn build reads this file and generates individual JSON files in public/r/.

# Build registry
bun run build:registry    # or: npx shadcn build

# Output
public/r/
├── registry.json         # Auto-generated index
├── faq.json              # Per-block JSON with embedded file contents
├── auth.json
└── ...

Adding a New Block

Add an entry to registry.json:

{
  "name": "my-block",
  "type": "registry:block",
  "title": "My Block",
  "description": "What it does.",
  "categories": ["shipkit", "my-category"],
  "dependencies": ["some-npm-package"],
  "registryDependencies": ["cn", "button"],
  "files": [
    {
      "path": "src/app/(app)/my-route/page.tsx",
      "type": "registry:page",
      "target": "~/app/(app)/my-route/page.tsx"
    }
  ],
  "docs": "Setup instructions shown after installation."
}

Run bun run build:registry to generate the output files.
Test locally (see Local Testing below).

Local Testing

To test registry blocks locally before deploying:

Option A: Use the dev server

# Terminal 1
bun dev

# Terminal 2
npx shadcn add http://localhost:3000/r/faq.json

Option B: Quick static server (no full Next.js build needed)

# Terminal 1
npx serve public/r -p 5555

# Terminal 2
npx shadcn add http://localhost:5555/faq.json

Resolving custom registry dependencies locally:

To fix this, add a local Shipkit registry to your test project's components.json:

{
  "registries": {
    "@shipkit": "http://localhost:3000/r/{name}.json"
  }
}

Then install via the registry prefix:

npx shadcn add @shipkit/faq

This resolves all internal deps (cn, routes-config, etc.) through the local server. Standard shadcn deps (accordion, button, etc.) still resolve from shadcn.com as normal.

File Entry Types

Type	Use for
`registry:page`	Route pages (`page.tsx`)
`registry:component`	React components, layouts, loading states
`registry:hook`	React hooks
`registry:lib`	Utilities, configs, server code, types, API routes
`registry:style`	CSS files

Target Paths

~ resolves to the project root (relative to components.json)
Always include (app) for routes: ~/app/(app)/my-route/page.tsx
Non-route files keep their path: ~/lib/my-util.ts, ~/hooks/my-hook.ts
path is the source location in Shipkit, target is where it installs in the consumer project

Registry Dependencies

Internal deps (defined in the same registry): cn, routes-config, features-config
shadcn deps (resolved from shadcn.com): accordion, button, card, input, etc.
Consumer projects resolve internal deps by adding the Shipkit registry to their components.json