Development Workflow

Relevant source files

• .github/workflows/prerelease-comment.yml
• .github/workflows/release.yml
• CONTRIBUTING.md
• README.md
• apps/v4/registry.json
• apps/v4/registry/README.md
• apps/v4/scripts/build-registry.mts

This document provides an overview of the development workflow for contributing to the shadcn/ui project. It covers environment setup, monorepo development practices, registry build pipelines, and the release process.

For detailed commit conventions and component contribution guidelines, see Contributing Guidelines. For in-depth information about release workflows and changesets, see Release Process.

---

Purpose and Scope

This page documents the practical workflow for developing and contributing to shadcn/ui. It covers:

• Setting up the development environment.
• Working with the pnpm monorepo structure.
• Building and testing the component registry locally.
• Testing the CLI in development.
• Overview of the release system.

For information about the monorepo structure itself, see Monorepo Structure. For build system details, see Build and Release System.

---

Development Environment Setup

Prerequisites

The project requires the following tools:

Tool	Purpose
pnpm	Package manager and workspace management CONTRIBUTING.md13
Turborepo	Build system and task orchestration CONTRIBUTING.md14
changesets	Release and changelog management CONTRIBUTING.md15

Sources: CONTRIBUTING.md13-15

Repository Setup

The standard fork-and-clone workflow applies:

Workflow Steps:

1. Fork the repository at https://github.com/shadcn-ui/ui CONTRIBUTING.md45-47
2. Clone your fork: git clone https://github.com/your-username/ui.git CONTRIBUTING.md49-53
3. Create a feature branch: git checkout -b my-new-branch CONTRIBUTING.md61-65
4. Install dependencies: pnpm install CONTRIBUTING.md67-71

Sources: CONTRIBUTING.md43-71 README.md11-13

---

Monorepo Development Workflow

Workspace Structure

The repository is a monorepo using pnpm workspaces with the following key directories:

apps/
└── v4/               # Next.js documentation website & Registry source
    ├── app/          # Next.js app directory
    ├── components/   # Website React components
    ├── content/      # MDX documentation files
    └── registry/     # Component registry source code
packages/
└── shadcn/           # The shadcn CLI package

Sources: CONTRIBUTING.md17-41

Running Workspaces

The monorepo uses workspace-scoped commands via the pnpm --filter syntax CONTRIBUTING.md73-75:

Note: On a fresh clone, you must run pnpm --filter=v4 registry:build --style all once before starting the dev server, as generated styles are not checked into git CONTRIBUTING.md85-89

Sources: CONTRIBUTING.md73-94

---

Testing the CLI Locally

CLI Development Workflow

To ensure the CLI correctly interacts with the registry and transforms code, follow this two-terminal workflow:

Workflow:

1. Start the development server: Run pnpm dev CONTRIBUTING.md97-99 This starts the v4 application which serves the local registry.
2. Test the CLI: In another terminal, run pnpm shadcn CONTRIBUTING.md104-105 This ensures it points to your local registry.
3. Cross-Project Testing: Use the -c flag to target an external test application: pnpm shadcn <init | add> -c ~/Desktop/my-app CONTRIBUTING.md107-115

Sources: CONTRIBUTING.md91-118

---

Working with Components

Component Registry Organization

The v4 registry uses a pipeline defined in apps/v4/scripts/build-registry.mts apps/v4/scripts/build-registry.mts28-35

• Authored Sources: Raw component source lives in registry/bases/base and registry/bases/radix apps/v4/scripts/build-registry.mts31-32
• Style Tokens: Design tokens are defined in registry/styles/style-*.css apps/v4/scripts/build-registry.mts34
• Legacy Source: new-york-v4 is authored directly and committed apps/v4/registry/README.md16-18

Registry Build Pipeline

The registry:build script handles the transformation of authored base components into style-specific variants (e.g., base-nova, radix-sera) apps/v4/scripts/build-registry.mts68-75

Modification Requirements:

1. Changes must be made for every style CONTRIBUTING.md145
2. Documentation in apps/v4/content/docs must be updated CONTRIBUTING.md146
3. Run pnpm registry:build to update artifacts CONTRIBUTING.md147

For local iteration, use targeted flags:

• --style <name>: Rebuilds local styles/<style>/ui apps/v4/scripts/build-registry.mts157
• --registry <name>: Rebuilds installable public/r/styles/<style> apps/v4/scripts/build-registry.mts158
• --examples: Rebuilds examples/__index__.tsx apps/v4/scripts/build-registry.mts155

Sources: apps/v4/scripts/build-registry.mts27-161 CONTRIBUTING.md130-159 apps/v4/registry/README.md1-101

---

Testing Infrastructure

The project uses Vitest for testing CONTRIBUTING.md203

• Root Test: Running pnpm test from the root runs all tests CONTRIBUTING.md207
• CLI Tests: Changes to the shadcn package should include tests in packages/shadcn CONTRIBUTING.md197-200

Sources: CONTRIBUTING.md195-210

---

Release Process Overview

Release management is automated via GitHub Actions and changesets.

• Stable Releases: Triggered on push to main. It builds packages (shadcn, @shadcn/react, @shadcn/helpers) and creates a version PR or publishes to NPM using changesets/action@v1 .github/workflows/release.yml120-174
• Prereleases: Triggered by labeling a PR with release: beta or release: rc .github/workflows/release.yml17-18 This publishes a snapshot version to NPM .github/workflows/release.yml105-107
• Feedback: After a prerelease is published, a comment is automatically added to the PR with installation instructions .github/workflows/prerelease-comment.yml68-74

For detailed information, see Release Process.

Sources: .github/workflows/release.yml1-178 .github/workflows/prerelease-comment.yml1-95