Monorepo

Core Idea

The shadcn CLI understands monorepo/workspace layouts: it installs components, dependencies and registry dependencies to the correct workspace and fixes import paths automatically, no manual path wrangling needed.

Key Concepts

• init --monorepo: Scaffolds a new monorepo with apps/web and packages/ui workspaces plus Turborepo, prompting for a framework template (Next.js, Vite, TanStack Start, React Router, Astro).
• Per-workspace components.json: Every workspace needs its own components.json; it must define aliases telling the CLI how to import components/hooks/utils for that workspace.
• @workspace/ui package: Shared UI package; components/hooks/utils are imported as @workspace/ui/components/button, @workspace/ui/hooks/use-theme, @workspace/ui/lib/utils.
• CLI run location matters: Run npx shadcn add [component] from inside the app path (cd apps/web); the CLI figures out whether the file belongs in packages/ui or apps/web/components.
• package.json#imports: Alternative to tsconfig.json paths — local #... aliases per workspace plus exports on the shared UI package for cross-workspace imports.

Code Examples

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "tailwind": { "config": "", "css": "../../packages/ui/src/styles/globals.css", "baseColor": "neutral", "cssVariables": true },
  "aliases": {
    "components": "@/components",
    "utils": "@workspace/ui/lib/utils",
    "ui": "@workspace/ui/components"
  }
}

• O que demonstra: alias ui/utils apontando pro pacote compartilhado @workspace/ui, alias components local ao app.

Reference Tables

Requirement	Detail
components.json per workspace	Required in every workspace (app + ui package)
Same style, iconLibrary, baseColor	Must match across all components.json files
Tailwind v4	Leave tailwind config field empty ("")

Anti-patterns

• style/iconLibrary/baseColor mismatched between workspaces: breaks the CLI's ability to install components coherently across the monorepo.
• Running add from the repo root instead of apps/web: the CLI needs the app's components.json context to route files correctly.

Key Takeaways

1. npx shadcn init --monorepo is the fastest path to a correctly wired Turborepo + shadcn setup.
2. npx shadcn add login-01 from apps/web splits files automatically: primitives (button, input, card) go to packages/ui, the composed login-form goes to apps/web/components.
3. For Tailwind v4 monorepos, always leave tailwind.config empty in components.json.
4. package.json#imports (local # aliases) coexists with components.json aliases; use #... for package-local files and explicit @workspace/ui/... exports for shared imports.

Connects To

• registry (ch098+): monorepo install paths use the same registry:ui/registry:component type routing as any registry.
• package-imports guide: referenced for framework-specific package.json#imports setup.