Installation

Prerequisites

• Node.js >= 22.0.0
• pnpm >= 9.0.0
• A Next.js project (16+ with App Router recommended)

Bootstrap (Recommended)

The fastest way to set up Buildpad UI is with the bootstrap command. It combines init + add all components + install deps + validate into a single non-interactive command.

npx @buildpad/cli@latest bootstrap --cwd /path/to/project

This installs:

• buildpad.json configuration + Next.js skeleton
• 40+ UI components in components/ui/
• Types, services, hooks in lib/buildpad/
• Design system (design-tokens.css, globals.css, lib/theme.ts) + app shell (ColorSchemeToggle, AuthenticatedShell) — tracked, refreshable via buildpad upgrade --design
• A wired app/[lang]/(authenticated)/layout.tsx that renders AuthenticatedShell around every authenticated page out of the box (customize the nav/brand)
• API proxy routes (fields, items, relations, files)
• Auth proxy routes (login, logout, user, OAuth callback) + login page
• Supabase auth utilities/middleware and OAuth helpers (lib/oauth/*)
• npm dependencies via pnpm install (incl. @supabase/ssr, @supabase/supabase-js, jose)

Manual Setup

cd your-nextjs-app
npx @buildpad/cli@latest init

# Add individual components
npx @buildpad/cli@latest add input select-dropdown datetime
 
# Add collection-form (includes VForm + all dependent interface components)
npx @buildpad/cli@latest add collection-form
 
# Add by category
npx @buildpad/cli@latest add --category selection

import { Input } from '@/components/ui/input';
import { SelectDropdown } from '@/components/ui/select-dropdown';
 
export default function MyPage() {
  return (
    <form>
      <Input label="Name" value={name} onChange={setName} />
      <SelectDropdown
        label="Category"
        choices={[
          { text: 'Blog', value: 'blog' },
          { text: 'News', value: 'news' },
        ]}
        value={category}
        onChange={setCategory}
      />
    </form>
  );
}

Project Structure

After adding components, your project will look like this:

your-project/
├── app/
│   ├── (authenticated)/
│   │   └── layout.tsx     # Renders AuthenticatedShell around authenticated pages
│   ├── api/
│   │   ├── auth/          # Auth proxy routes
│   │   ├── fields/        # Fields proxy
│   │   ├── items/         # Items proxy
│   │   ├── relations/     # Relations proxy
│   │   └── files/         # Files proxy
│   └── login/page.tsx     # Login page
├── components/
│   └── ui/                # UI components (copied source)
├── lib/
│   └── buildpad/          # Lib modules (auto-resolved)
│       ├── types/
│       ├── services/
│       ├── hooks/
│       └── utils/
└── buildpad.json          # Configuration