Project Initialization: From Empty Directory to Configured Component System

Everything in Articles 2–4 assumes a project with a components.json. This article covers how that file gets created. The init command is the most interactive part of shadcn/ui — it detects your framework, offers preset selections, scaffolds new projects from templates, and configures your project's component system. It also has a secret second life: the add command triggers auto-init when no configuration exists.

The init Command: Decision Tree

The init command, aliased as create, accepts components as variadic arguments alongside configuration flags. The decision flow is complex:

flowchart TD
    A["shadcn init"] --> B{Has components.json?}
    B -->|Yes| C{--force flag?}
    C -->|No| D["Prompt: overwrite?"]
    C -->|Yes| E["Continue with force"]
    B -->|No| F{Has package.json?}
    F -->|No| G["Scaffold new project"]
    F -->|Yes| H["Configure existing project"]
    G --> I["Select template"]
    I --> J["Select base: Radix or Base UI"]
    J --> K["Select preset"]
    K --> L["runInit()"]
    H --> M["Detect framework"]
    M --> J
    D -->|Yes| N["Backup existing config"]
    N --> L

A components.json backup mechanism (line 131-141) protects against failed initializations. If the process crashes or the user exits, a process.on("exit") handler restores the backup. This is essential because the init process temporarily removes components.json before the preflight checks.

The command also detects monorepo roots. If you're in a workspace root without a components.json, it suggests running init in a specific workspace package instead, listing available targets.

Framework Detection

The FRAMEWORKS object defines 11 recognized frameworks. Detection happens in getProjectInfo, which runs several checks in parallel:

flowchart TD
    A["getProjectInfo(cwd)"] --> B["glob for config files"]
    A --> C["Check src/ directory"]
    A --> D["Check TypeScript"]
    A --> E["Find tailwind config"]
    A --> F["Detect Tailwind version"]
    A --> G["Read tsconfig alias prefix"]
    A --> H["Read package.json"]
    B --> I{next.config.*?}
    I -->|Yes + app dir| J["next-app"]
    I -->|Yes + pages dir| K["next-pages"]
    B --> L{vite.config.*?}
    L -->|Yes| M["vite"]
    B --> N{astro.config.*?}
    N -->|Yes| O["astro"]
    B --> P{react-router.config.*?}
    P -->|Yes| Q["react-router"]
    B --> R{composer.json?}
    R -->|Yes| S["laravel"]

The detection glob (**/{next,vite,astro,app}.config.*|gatsby-config.*|composer.json|react-router.config.*) searches up to 3 directories deep, ignoring node_modules. The result is a ProjectInfo struct with framework, TypeScript status, Tailwind version, alias prefix, and whether a src/ directory exists.

Tip: If framework detection fails, shadcn defaults to manual. You can still use the CLI, but you'll get more prompts because the system can't infer defaults like RSC support or directory structure.

The Template System

Templates are defined via the createTemplate factory and registered in templates/index.ts:

Template Key	Frameworks	Has Monorepo?
next	next-app, next-pages	Yes
vite	vite	Yes
start	tanstack-start	Yes
react-router	react-router	Yes
astro	astro	Yes
laravel	laravel	No (requires laravel new first)

Each template provides a TemplateConfig with:

• scaffold: Downloads the template from GitHub via sparse checkout
• create: Framework-specific project creation (e.g., create-next-app)
• init: Writes components.json and installs initial components
• postInit: Runs git init and creates an initial commit
• monorepo: Override config for --monorepo mode

The default scaffold at lines 218-299 uses Git sparse checkout to download only the template directory rather than the entire repository:

git clone --depth 1 --filter=blob:none --sparse https://github.com/shadcn-ui/ui.git
git sparse-checkout set templates/next-app

After cloning, the scaffold adapts workspace configuration for the user's package manager. pnpm-based template lockfiles are removed for other package managers, pnpm-workspace.yaml is converted to package.json workspaces, and workspace: protocol references are rewritten for npm.

Presets and Theme Configuration

The DEFAULT_PRESETS object defines six built-in presets:

classDiagram
    class PresetNova {
        style: "nova"
        iconLibrary: "lucide"
        font: "geist"
        menuAccent: "subtle"
    }
    class PresetVega {
        style: "vega"
        iconLibrary: "lucide"
        font: "inter"
    }
    class PresetMaia {
        style: "maia"
        iconLibrary: "hugeicons"
        font: "figtree"
    }
    class PresetLyra {
        style: "lyra"
        iconLibrary: "phosphor"
        font: "jetbrains-mono"
    }
    class PresetMira {
        style: "mira"
        iconLibrary: "hugeicons"
        font: "inter"
    }
    class PresetLuma {
        style: "luma"
        iconLibrary: "lucide"
        font: "inter"
    }

Each preset specifies style, base color, theme, icon library, font, menu accent, and menu color. When selected, the preset is encoded into a URL: https://ui.shadcn.com/init?base=radix&style=nova&baseColor=neutral&.... This URL points to a registry:base item that carries the full configuration as its config field.

The --defaults flag is a shortcut: it selects the nova preset with the next template, skipping all interactive prompts. This is useful for CI environments or quick project setup.

The add Command and Auto-Init

The add command handles the common case of adding components to an existing project. But it has a critical fallback: if no components.json exists, it triggers the full init flow.

flowchart TD
    A["shadcn add button"] --> B["preflight check"]
    B --> C{components.json exists?}
    C -->|Yes| D["Resolve registry items"]
    C -->|No| E["Prompt: create config?"]
    E -->|Yes| F["Detect framework"]
    F --> G["Prompt for base + preset"]
    G --> H["runInit() with components"]
    H --> I["Config created + components installed"]
    D --> J["Transform source"]
    J --> K["Write files"]
    K --> L["Install npm dependencies"]

At line 161, when MISSING_CONFIG is detected, the add command prompts the user, infers the template from the detected framework, runs through base and preset selection, and calls runInit with the originally requested components included. After init completes, the components are already installed — no second add call needed.

The add command also handles:

• --all flag: Installs every component from the registry index (excluding deprecated ones like toast)
• --dry-run: Previews what would change without writing files
• --diff: Shows a diff of what would change in existing files
• Universal items: registry:file and registry:item types are installed immediately without the full preflight flow
• Style/theme confirmation: Installing a registry:style or registry:theme warns about CSS variable overwrite

Tip: Running shadcn add button in a fresh project is a perfectly valid way to set up shadcn/ui. You'll be guided through init automatically, and the button component will be installed as part of the same flow.

Monorepo Workspace Routing

When the project uses a monorepo, addComponents at packages/shadcn/src/utils/add-components.ts detects whether the ui alias resolves to a different package than the current working directory. If so, it delegates to addWorkspaceComponents, which routes files to the appropriate packages:

• registry:ui files → the ui package (where the alias points)
• registry:hook, registry:page, registry:block files → the app package
• CSS updates → the app's stylesheet
• npm dependencies → split between the ui package and app package

This routing relies on getWorkspaceConfig, which resolves each alias path to its containing package.json root. If the components alias points to ../../packages/ui/src/components, it finds the packages/ui package root and loads its own components.json.

Design settings (menu color, menu accent, RTL, icon library) are propagated to workspace components.json files during init, ensuring consistency across a monorepo.

What's Next

We've covered how projects get configured and how components get installed. The final piece of the architecture is the AI integration layer. In Part 6, we'll explore the MCP server that exposes the registry to AI coding assistants, the programmatic API for library consumers, and how shadcn/ui's triple-surface design enables all three consumption patterns from a single codebase.