heroui: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

HeroUI v3 is a modern React UI library built with Tailwind CSS v4, using a pnpm monorepo structure managed by Turborepo.

Key Technical Stack

• Node.js: v22+ required
• pnpm: v10.26.2 (package manager)
• React: v19+
• Tailwind CSS: v4.3.3
• TypeScript: v5.9.3
• Turborepo: Build orchestration
• Storybook: Component development
• Vitest: Testing framework

Use the workspace manifests and lockfile as the source of truth for exact dependency versions.

Development Commands

Core Development Commands

# Install dependencies (use --hoist flag)
pnpm i --hoist

# Start Storybook for component development
pnpm dev

# Start documentation site
pnpm dev:docs

# Build libraries (styles + React)
pnpm build

# Build React and its dependencies
pnpm build:react

# Build docs or Storybook
pnpm build:docs
pnpm build:storybook

# Run linting
pnpm lint

# Run tests (turbo → packages with a test script; jsdom + browser)
pnpm test

# Filter by file name (e.g. button.test.tsx)
pnpm --filter @heroui/react exec vitest run button

# Coverage (jsdom floors only — not a depth bar)
pnpm test:coverage

# Changed-set (local jsdom only; not a merge gate)
pnpm --filter @heroui/react test:changed

# Check formatting
pnpm run format

# Apply formatting fixes
pnpm run format:fix

# Run type checking
pnpm typecheck

Behavioral tests (@heroui/react)

• Suites: packages/react/tests/components/<name>/ — *.test.tsx (jsdom), *.ssr.test.tsx (Client SSR via ssrSmoke(), not RSC), *.browser.test.tsx (Playwright for high-risk portals/overlays; not universal), optional fixtures.tsx
• Harness: @heroui/testing/helpers (render, setupUser, runAllTimers, ssrSmoke, User); browser render from @heroui/testing/browser. Sources via @/. Pattern testers: user.createTester(...) — do not import createTester directly
• Query/assert: role/label/text first; HeroUI data-* + light BEM + documented data-slot on compound parts; no colors, full class lists, or RAC internals
• Timers: fake timers per-suite only; wire advanceTimers into setupUser + User
• Naming: describe("Component"); nested concern; it as supports… / calls… / exposes… / renders…. SSR: "Component SSR"; browser: "Component (browser)"
• Intentional skips: internals (rac, icons), non-exported helpers (color-input-group, date-input-group), in-progress calendar-year-picker, parent-covered parts (list-box-item, menu-item, …), Toast SSR (client portal — jsdom + browser). Public input-group has its own suite. SSR/browser are risk-based
• Browser setup (once locally): pnpm --filter @heroui/testing exec playwright install chromium before pnpm test. PR QA uses the same command with --with-deps, then pnpm test:browser + pnpm test:coverage. Release CI installs Chromium and runs pnpm test
• Commands: pnpm test (jsdom + browser, needs Chromium); filter with pnpm --filter @heroui/react exec vitest run <name>
• Coverage: jsdom-only floors — green ≠ depth. Browser suites contribute nothing to the coverage number. Floors are a ratchet kept ~1pt under the measured run: raise them as coverage improves, never lower them to go green. test:changed: local jsdom shortcut only, not a merge gate
• SSR/browser suites are risk-based — see "When a component needs an SSR or browser suite" in AGENTS.md. Add a browser suite when correctness depends on real layout, pointer capture, portal focus containment, or transitions; do not fake geometry in jsdom to chase coverage