Getting Started

Installation

Create a new app or initialize an existing React project. First-class setup for Next.js, TanStack Start, React Router and Vite, with npm, pnpm, Yarn and Bun.

Create a new application

The create command runs your framework’s official scaffolder, installs dependencies and initializes baseui-cn. Run it without flags for guided setup.

npx baseui-cn@latest create my-app --framework next

# Choose your framework
npx baseui-cn@latest create my-app --framework tanstack-start
npx baseui-cn@latest create my-app --framework react-router
npx baseui-cn@latest create my-app --framework vite

# Choose a package manager
pnpm dlx baseui-cn@latest create my-app --framework next --package-manager pnpm

Install the chosen package manager first. Yarn runners require Yarn 2+. New projects use current upstream scaffolders; Node.js 22.12+ is recommended, and upstream runtime requirements apply. Existing/custom React apps use init with their own Tailwind CSS v4 pipeline and @/* source alias.

Create a new monorepo

Run create with --monorepo to generate a new workspace root and its application in apps/web. The project name is a new directory, never an existing workspace path.

npx baseui-cn@latest create my-app --framework next --package-manager pnpm --monorepo

New apps retain strict TypeScript checks and match the registry’s compiler policy: noUnusedLocals and noUnusedParameters are disabled. Existing compiler settings stay yours; Data Grid contains two unused bindings to clean up locally if those options are enabled.

Choose a theme

Fresh setup defaults to Iris, Rounded and system typography. Create and init accept --color, --radius, --body-font and --heading-font. Existing appearance is preserved unless you explicitly pass those flags or choose new values interactively. Color applies the complete light/dark palette, including border, input and ring; radius controls the derived radii.

pnpm dlx baseui-cn@latest create my-app --framework next --package-manager pnpm --color iris --radius lg --body-font inter --heading-font space-grotesk
npx baseui-cn@latest init --body-font inter --heading-font montserrat

Body fonts: system, inter, geist, manrope, roboto. Heading fonts: system, inter, geist, manrope, montserrat, poppins, space-grotesk. Non-system fonts are installed from pinned Fontsource npm packages and bundled by your app; no Google Fonts runtime service is used. Matching selections install/import once. System adds no font dependency. Poppins uses static weights 400–900; other selections use variable normal faces. Add italic or extra faces in your own app when needed.

Consumers own --font-body and --font-heading. Body and semantic h1–h6 headings use their respective tokens; code and icons keep their own typography. Interactive init offers “Keep existing typography” first, even when custom typography cannot be detected.

View color and radius presets

Initialize an existing application

Run init inside your app or at your workspace root. The CLI detects frameworks, lockfiles, packageManager declarations and common workspace configurations. A single app is selected automatically; multiple apps prompt for a target. Noninteractive runs with multiple apps require --workspace.

npx baseui-cn@latest init

Initialize an app in an existing monorepo

Run this from the existing workspace root. --workspace is an optional existing member path such as apps/web. It never creates a new project or monorepo.

# Paths are relative to the existing workspace root
npx baseui-cn@latest init --workspace apps/web
npx baseui-cn@latest add button --workspace apps/web
npx baseui-cn@latest update button --workspace apps/web

# Choose custom component, utils and CSS paths
npx baseui-cn@latest init --customize

Component files, utilities, configuration and dependencies belong to the selected app. Shared packages/ui generation is not included. Custom workspace globs with braces/extglobs or application layouts that cannot be detected should be initialized from inside the application.

Requirements

Node.js18.0 or later

React18.0 or later

Next.js15+ with App Router (recommended) or any React 18+ project

Tailwind CSSv4 (CSS-first config)

@base-ui/reactInstalled automatically by init

Step 1 — Initialize

Run this in your project root. It auto-detects your structure and sets everything up.

npx baseui-cn init

Prefer a specific stylesheet? Pass --css src/styles.css and baseui-cn will use that path instead of guessing.

Detects projectFinds Next.js, TanStack Start, React Router, Vite, React and application source directories

Installs deps@base-ui/react · clsx · tailwind-merge · class-variance-authority

CSS variablesPrompts for your stylesheet and injects theme tokens, including destructive, success, warning, and info

UtilsCreates lib/utils.ts with the cn() helper

ConfigWrites baseui-cn.json with your resolved paths

Step 2 — Add components

Each component is copied directly into your project. You own the code.

npx baseui-cn add button

Add several at once:

npx baseui-cn add dialog drawer select combobox

Or add everything:

npx baseui-cn add --all

Step 3 — Import and use

Components land in components/ui/. Import and use immediately.

import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle } from "@/components/ui/drawer"

export default function Page() {
  return (
    <Drawer>
      <DrawerTrigger render={<Button variant="outline">Open</Button>} />
      <DrawerContent side="right">
        <DrawerHeader>
          <DrawerTitle>Settings</DrawerTitle>
        </DrawerHeader>
        <div className="p-6">
          <Input label="Display name" placeholder="Aria Chen" />
        </div>
      </DrawerContent>
    </Drawer>
  )
}

baseui-cn.json

Created at your project root by init. Edit to change where components, utils, and theme styles are placed.

{
  "componentsPath": "src/components/ui",
  "utilsPath": "src/lib/utils",
  "globalCss": "src/app/globals.css",
  "tailwind": true,
  "rsc": true
}

Manual installation

Prefer to set things up yourself? Install the dependencies and copy components manually.

pnpm add @base-ui/react class-variance-authority clsx tailwind-merge

Then add the CSS variables from the Theming page to your main stylesheet and create lib/utils.ts:

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

Already have a design system?

baseui-cn uses the same CSS variable naming convention as other registry-style systems. If you already have --background, --primary, etc. in your stylesheet, components will pick them up automatically.

Theming →LLM usage →