# What Does the shadcn init Command Do and How Does It Configure Project Paths?

> Discover what the shadcn init command does. Learn how it bootstraps your project, resolves paths, and configures components.json for shadcn/ui.

- Repository: [shadcn-ui/ui](https://github.com/shadcn-ui/ui)
- Tags: how-to-guide
- Published: 2026-02-26

---

**The `shadcn init` command bootstraps a shadcn/ui project by validating the working directory, optionally scaffolding a new framework project, resolving absolute paths through `resolveConfigPaths`, and generating a [`components.json`](https://github.com/shadcn-ui/ui/blob/main/components.json) file that maps component locations, Tailwind configuration, and alias imports.**

The `shadcn init` command serves as the primary entry point for integrating shadcn/ui into React applications. It performs pre-flight checks, handles project scaffolding when needed, and critically configures project paths to ensure components, styles, and Tailwind settings resolve correctly. Understanding how the command resolves and writes these paths is essential for troubleshooting setup issues and customizing your development workflow.

## Core Responsibilities of the shadcn init Command

According to the shadcn/ui source code, the `init` command executes three high-level tasks:

1. **Pre-flight checks and optional scaffolding** – Validates the working directory for an existing framework installation and can generate a fresh project using built-in templates (Next.js, Vite, etc.) if the directory is empty.
2. **Configuration discovery and path resolution** – Reads or creates [`components.json`](https://github.com/shadcn-ui/ui/blob/main/components.json), resolves all paths into absolute references, and merges registry defaults with user preferences.
3. **Component installation and Tailwind configuration** – Installs the base style index and requested components, then updates Tailwind content paths to recognize the project structure.

## How shadcn init Configures Project Paths: Step-by-Step

### 1. Command Parsing and Option Validation

The command definition resides in **[`packages/shadcn/src/commands/init.ts`](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/commands/init.ts)**, where the CLI arguments are defined and validated:

```typescript
export const init = new Command()
  .name("init")
  .description("initialize your project and install dependencies")
  .option("-c, --cwd <cwd>", "the working directory. defaults to the current directory.", process.cwd())
  .option("--src-dir", "use the src directory when creating a new project.", false)

```

All options are validated against the `initOptionsSchema` Zod schema (lines 63–107). The **`--cwd`** flag determines the project root, while **`--src-dir`** influences whether generated files are placed under a `src/` subdirectory during scaffolding.

### 2. Pre-Flight Validation and Optional Scaffolding

The `runInit` function executes `preFlightInit` to detect the environment:

```typescript
if (!options.skipPreflight) {
  const preflight = await preFlightInit(options)
  if (preflight.errors[ERRORS.MISSING_DIR_OR_EMPTY_PROJECT]) {
    const { projectPath, template } = await createProject(options)
    options.cwd = projectPath            // New project root assigned
    options.isNewProject = true
  }
}

```

If the target directory lacks a supported framework, `createProject` (from [`utils/create-project.ts`](https://github.com/shadcn-ui/ui/blob/main/utils/create-project.ts)) scaffolds a new project. Critically, **`options.cwd` is updated to the newly created directory**, ensuring all subsequent path resolution uses the correct root.

### 3. Resolving Absolute Paths with resolveConfigPaths

Before writing configuration, the command resolves all relative paths into absolute references:

```typescript
const fullConfigForRegistry = await resolveConfigPaths(options.cwd, config)

```

The `resolveConfigPaths` function in **[`utils/get-config.ts`](https://github.com/shadcn-ui/ui/blob/main/utils/get-config.ts)** expands relative entries such as [`tailwind.css`](https://github.com/shadcn-ui/ui/blob/main/tailwind.css), `tailwind.config`, and TypeScript aliases into absolute paths based on the resolved `options.cwd`. If `--src-dir` was used during project creation, this function ensures that later steps target the `src/` folder correctly.

### 4. Writing the components.json Configuration

The command constructs the final configuration object and writes it to disk:

```typescript
const targetPath = path.resolve(options.cwd, "components.json")
await fs.writeFile(targetPath, `${JSON.stringify(config, null, 2)}\n`, "utf8")

```

The target path is always calculated relative to `options.cwd`, ensuring [`components.json`](https://github.com/shadcn-ui/ui/blob/main/components.json) lands in the project root regardless of whether the user specified `--cwd` or a new project was just scaffolded.

### 5. Installing Components and Updating Tailwind

The command installs the base style (the "index" component) and any user-requested components:

```typescript
const components = [
  ...(options.installStyleIndex ? ["index"] : []),
  ...(options.components ?? []),
]
await addComponents(components, fullConfig, { overwrite: true, … })

```

If a new project was created with `--src-dir`, the Tailwind content configuration is automatically updated:

```typescript
if (options.isNewProject && options.srcDir) {
  await updateTailwindContent(
    ["./src/**/*.{js,ts,jsx,tsx,mdx}"],
    fullConfig,
    { silent: options.silent }
  )
}

```

The `updateTailwindContent` function in **[`utils/updaters/update-tailwind-content.ts`](https://github.com/shadcn-ui/ui/blob/main/utils/updaters/update-tailwind-content.ts)** rewrites the `content` array in [`tailwind.config.js`](https://github.com/shadcn-ui/ui/blob/main/tailwind.config.js) to ensure Tailwind scans the correct directories.

## Practical CLI Usage Examples

Initialize in the current directory:

```bash
npx shadcn-ui@latest init

```

Create a new Next.js project with src directory structure:

```bash
npx shadcn-ui@latest init -c ./my-app -t next --src-dir

```

Skip prompts and force overwrite existing configuration:

```bash
npx shadcn-ui@latest init -y -d -f

```

## Key Implementation Files

| File Path | Role in Path Configuration |
|-----------|---------------------------|
| [`packages/shadcn/src/commands/init.ts`](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/commands/init.ts) | Main command implementation, option parsing, and orchestration of the init flow (lines 78–89, 96–106). |
| [`packages/shadcn/src/utils/create-project.ts`](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/utils/create-project.ts) | Generates new projects from templates and returns the new root path for `options.cwd`. |
| [`packages/shadcn/src/utils/get-config.ts`](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/utils/get-config.ts) | Contains `resolveConfigPaths` which converts relative paths to absolute paths based on the working directory. |
| [`packages/shadcn/src/preflights/preflight-init.ts`](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/preflights/preflight-init.ts) | Performs environment checks to determine if scaffolding is required before path resolution. |
| [`packages/shadcn/src/utils/updaters/update-tailwind-content.ts`](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/utils/updaters/update-tailwind-content.ts) | Updates Tailwind config content globs, particularly when using the `--src-dir` flag. |
| [`packages/shadcn/src/utils/get-project-info.ts`](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/utils/get-project-info.ts) | Detects framework type and versions used during pre-flight validation. |

## Summary

- The `shadcn init` command uses **`--cwd`** to establish the project root and **`--src-dir`** to influence directory structure during scaffolding.
- Path resolution occurs through **`resolveConfigPaths`** in [`get-config.ts`](https://github.com/shadcn-ui/ui/blob/main/get-config.ts), which converts relative configuration entries into absolute paths.
- When creating new projects, **`options.cwd`** is dynamically updated to the new directory, ensuring [`components.json`](https://github.com/shadcn-ui/ui/blob/main/components.json) and components install in the correct location.
- The command automatically updates Tailwind content paths when the `src/` directory layout is detected.
- All configuration is centralized in **[`components.json`](https://github.com/shadcn-ui/ui/blob/main/components.json)**, written relative to the resolved working directory.

## Frequently Asked Questions

### What is the default working directory for shadcn init?

By default, the command uses `process.cwd()` as the working directory. You can override this with the `-c` or `--cwd` flag to target a specific folder without navigating to it in your terminal.

### How does the --src-dir flag affect project structure?

When creating a new project with `--src-dir`, the scaffolder places source files under a `src/` subdirectory instead of the project root. The `resolveConfigPaths` function and `updateTailwindContent` utility automatically adjust all internal paths and Tailwind globs to reference `./src/**/*` rather than `./*`.

### Where does shadcn init write the components.json file?

The command writes [`components.json`](https://github.com/shadcn-ui/ui/blob/main/components.json) to `path.resolve(options.cwd, "components.json")`. This ensures the configuration file always resides at the project root, whether you are initializing in an existing directory or a freshly scaffolded project.

### Can I run shadcn init in an existing project without creating a new one?

Yes. If `preFlightInit` detects an existing supported framework (Next.js, Vite, etc.), it skips the `createProject` step and proceeds directly to configuration discovery and component installation, preserving your existing directory structure.