TypeScript 7,957 FILES 10 FINDINGS

HOW SHADCN/UI
ACTUALLY WORKS

Beautifully designed components built with Radix UI and Tailwind CSS. Conventions, patterns, and architecture extracted from the shadcn-ui/ui repository by sourcebook.

VIEW_REPO north_east

QUICK_REF:

Testing: Vitest. Test utilities in: packages/tests/src/utils/helpers.ts.

WHAT_MATTERS

→
This is a monorepo — check workspace dependencies before modifying shared code
→
Generated files detected — editing them directly will break builds
→
packages/shadcn/src/templates/create-template.ts is a hub file (imported by 9 files) — changes here ripple everywhere
→
Circular import chains detected — avoid adding to these cycles

KEY_FINDINGS

This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.

HIGH

Tests are co-located with source files (*.test.ts next to *.ts). Keep this pattern -- don't create a separate test/ directory.

HIGH

Tests use Vitest. Test utilities in: packages/tests/src/utils/helpers.ts.

HIGH

12 test files

Styling uses Tailwind CSS utility classes. Custom design tokens defined in packages/shadcn/test/fixtures/next-src/tailwind.config.js — use these instead of arbitrary values.

HIGH

39 files

Generated files detected (packages/tests/fixtures/next-app-init/app/layout.tsx, packages/tests/fixtures/next-app/app/layout.tsx, packages/shadcn/test/fixtures/next-app-js/app/layout.js, packages/shadcn/test/fixtures/frameworks/t3-pages/src/pages/index.tsx, templates/start-monorepo/apps/web/src/routeTree.gen.ts, ...). Do NOT edit these directly — modify the source/schema they are generated from.

HIGH

6 generated files

Hub files (most depended on): packages/shadcn/src/templates/create-template.ts (imported by 9 files); apps/v4/registry/icons/create-icon-loader.tsx (imported by 5 files). Changes here have the widest blast radius.

HIGH

Circular import chains detected: routeTree.gen.ts → router.tsx; routeTree.gen.ts → router.tsx. Avoid adding to these cycles.

HIGH

+ 2 MORE FINDINGS (MEDIUM CONFIDENCE)

Project prefers default exports. Use `export default` for main module exports.

MED

58 default vs 5 named exports in sampled files

UI components live in: templates/vite-monorepo/apps/web/src/components, templates/vite-app/src/components, templates/next-monorepo/apps/web/components. Add new components here.

MED

3 component directories

smart_toy USING_AI_TOOLS

→avoid editing generated files — modify the source/schema instead
→check file importance before editing hub files
→follow existing patterns listed in quick reference

CLAUDE.MD expand_more

# CLAUDE.md

This file provides guidance to Claude Code when working with this codebase.
Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.

## Quick Reference

- **testing:** Tests use Vitest. Test utilities in: packages/tests/src/utils/helpers.ts.
- **components:** UI components live in: templates/vite-monorepo/apps/web/src/components, templates/vite-app/src/components, templates/next-monorepo/apps/web/components. Add new components here.

## Commands

- **Dev:** `turbo run dev --parallel`
- **Build:** `turbo run build`
- **Test:** `start-server-and-test v4:dev http://localhost:4000 test:dev`
- **Lint:** `turbo run lint`
- **typecheck:** `turbo run typecheck`

## Critical Constraints

- **Testing:** Tests are co-located with source files (*.test.ts next to *.ts). Keep this pattern -- don't create a separate test/ directory.
- **Critical constraints:** Generated files detected (packages/tests/fixtures/next-app-init/app/layout.tsx, packages/tests/fixtures/next-app/app/layout.tsx, packages/shadcn/test/fixtures/next-app-js/app/layout.js, packages/shadcn/test/fixtures/frameworks/t3-pages/src/pages/index.tsx, templates/start-monorepo/apps/web/src/routeTree.gen.ts, ...). Do NOT edit these directly — modify the source/schema they are generated from.
- **Core modules:** Hub files (most depended on): packages/shadcn/src/templates/create-template.ts (imported by 9 files); apps/v4/registry/icons/create-icon-loader.tsx (imported by 5 files). Changes here have the widest blast radius.
- **Circular dependencies:** Circular import chains detected: routeTree.gen.ts → router.tsx; routeTree.gen.ts → router.tsx. Avoid adding to these cycles.

## Stack

Next.js, Tailwind CSS, TypeScript

## Project Structure

- `scripts/` — Build / utility scripts

## Core Modules (by structural importance)

- `packages/shadcn/src/templates/create-template.ts`
- `apps/v4/registry/icons/create-icon-loader.tsx`
- `packages/shadcn/src/registry/api.ts`
- `packages/shadcn/src/utils/transformers/transform-css-vars.ts`
- `packages/shadcn/src/templates/monorepo.ts`

## Conventions & Patterns

- **Project structure:** This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.
- **Dominant patterns:**
- Tests use Vitest. Test utilities in: packages/tests/src/utils/helpers.ts.
- Styling uses Tailwind CSS utility classes. Custom design tokens defined in packages/shadcn/test/fixtures/next-src/tailwind.config.js — use these instead of arbitrary values.

## Additional Context

- **Export conventions:** Project prefers default exports. Use `export default` for main module exports.
- **Dominant patterns:** UI components live in: templates/vite-monorepo/apps/web/src/components, templates/vite-app/src/components, templates/next-monorepo/apps/web/components. Add new components here.

## Before Making Changes

- **Check file importance** before editing. Hub files (listed in Core Modules) affect many other files — changes here have the widest blast radius.
- **Follow existing patterns.** This project has established conventions (listed above). Match them instead of introducing new approaches.
- **Respect constraints.** Review the Critical Constraints section before making structural changes.

If the sourcebook MCP server is available (`sourcebook serve`), verify before acting:
- `get_blast_radius` — check what breaks if you edit a hub file
- `query_conventions` — confirm the right pattern before adding new code
- `get_pressing_questions` — get a briefing before editing an unfamiliar file

## What to Add Manually

The most valuable context is what only you know. Add:

- Architectural decisions and why they were made
- Past incidents that shaped current conventions
- Deprecated patterns to avoid in new code
- Domain-specific rules or terminology
- Environment setup beyond what .env.example shows

GENERATED IN ~3 SECONDS WITH

npx sourcebook init

VIEW ON GITHUB star

FROM_THE_BLOG

Why AI agents fail on real codebases arrow_forward Why auto-generated context makes agents worse arrow_forward

RELATED_REPOS

NEXT.JS CREATE T3 APP

HOW SHADCN/UIACTUALLY WORKS

WHAT_MATTERS

KEY_FINDINGS

npx sourcebook init

FROM_THE_BLOG

RELATED_REPOS

HOW SHADCN/UI
ACTUALLY WORKS