Build and Release System

Relevant source files

• .github/changeset-version.js
• .github/version-script-next.js
• .github/workflows/prerelease-comment.yml
• .github/workflows/release.yml
• .github/workflows/templates.yml
• packages/shadcn/src/utils/env-helpers.test.ts
• packages/shadcn/src/utils/env-helpers.ts
• packages/shadcn/src/utils/updaters/update-env-vars.test.ts
• packages/shadcn/src/utils/updaters/update-env-vars.ts
• templates/astro-app/pnpm-workspace.yaml
• templates/astro-monorepo/pnpm-workspace.yaml
• templates/next-app/pnpm-workspace.yaml
• templates/next-monorepo/pnpm-workspace.yaml
• templates/react-router-app/pnpm-workspace.yaml
• templates/react-router-monorepo/pnpm-workspace.yaml
• templates/start-app/pnpm-workspace.yaml
• templates/vite-app/pnpm-workspace.yaml
• templates/vite-monorepo/pnpm-workspace.yaml

This page documents the build orchestration, versioning, and release infrastructure for the shadcn/ui monorepo. The system uses Turborepo for parallel build execution, pnpm workspaces for dependency management, Changesets for versioning, and GitHub Actions for automated releases, prereleases, and template validation.

---

Release Workflows

The repository employs two primary GitHub Actions workflows for distributing packages: a stable release workflow for official versions and a prerelease workflow for testing pull requests.

Stable Release Workflow

• Trigger: When code is pushed to the main branch .github/workflows/release.yml12-14
• Goal: To create a new stable release by either generating a version bump pull request or publishing packages to npm.
• Key Tool: changesets/action@v1 manages release versioning and publication .github/workflows/release.yml168-174
• Build: Runs pnpm build:packages to build all publishable packages (e.g., shadcn, @shadcn/react, @shadcn/helpers) .github/workflows/release.yml155-156
• GPG Signing: Uses a GPG private key to sign commits and tags .github/workflows/release.yml158-164
• Version Script: Runs a custom .github/changeset-version.js script that executes changeset version followed by pnpm install --lockfile-only to keep the lockfile in sync .github/changeset-version.js1-13

Stable Release Pipeline

Sources: .github/workflows/release.yml120-178 .github/changeset-version.js1-13

---

Prerelease Workflow

• Trigger: When a Pull Request is labeled with release: beta or release: rc .github/workflows/release.yml8-11 .github/workflows/release.yml18
• Purpose: To publish snapshot versions for testing without affecting the stable latest tag.
• Process:
  • Detects the prerelease channel (beta or rc) from the PR label .github/workflows/release.yml27-51
  • Checks for the presence of changeset files in .changeset/ .github/workflows/release.yml78-89
  • Runs pnpm exec changeset version --snapshot to generate timestamped versions .github/workflows/release.yml97-99
  • Publishes to npm using the specific channel tag (e.g., --tag beta) .github/workflows/release.yml105-107
  • Generates a prerelease-info.json artifact containing package names and versions .github/workflows/release.yml109-119

Prerelease Feedback Loop

A separate workflow, prerelease-comment.yml, provides feedback to developers after the release job completes.

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

---

Template Validation System

The repository includes an extensive template validation system to ensure that the CLI can correctly scaffold and initialize projects across different frameworks and package managers.

Validation Strategy

The templates.yml workflow uses a matrix strategy to test combinations of:

• Frameworks: next, vite, astro, start, react-router .github/workflows/templates.yml29
• Package Managers: pnpm (v10 & v11), bun, npm, yarn .github/workflows/templates.yml30-31

Validation Logic

The workflow builds the CLI (pnpm --filter=shadcn build) and the registry (pnpm --filter=v4 registry:build) .github/workflows/templates.yml88-92 It then executes a bash script that:

1. Generates a project from a template in templates/ .github/workflows/templates.yml119-122
2. Validates package.json for correct package manager fields and workspace configurations .github/workflows/templates.yml152-194
3. Ensures no pnpm artifacts (like pnpm-lock.yaml) exist in non-pnpm projects .github/workflows/templates.yml146-147

Sources: .github/workflows/templates.yml1-152 templates/next-app/pnpm-workspace.yaml1-8

---

Environment Variable Management

The CLI includes utilities for managing .env files, ensuring that components requiring environment variables (like AI SDK keys) are configured correctly during installation.

Key Utilities

• findExistingEnvFile: Locates the appropriate environment file (e.g., .env.local) packages/shadcn/src/utils/env-helpers.ts51-78
• mergeEnvContent: Merges new variables into existing content without duplicates packages/shadcn/src/utils/env-helpers.ts80-114
• updateEnvVars: The high-level updater that reads, merges, and writes the environment file packages/shadcn/src/utils/updaters/update-env-vars.ts15-108

Environment Update Flow

Sources: packages/shadcn/src/utils/updaters/update-env-vars.ts1-108 packages/shadcn/src/utils/env-helpers.ts1-114

---

Summary of CI/CD Tasks

Task	Workflow / Script	Tooling
Stable Release	release.yml	Changesets, GPG, pnpm
Snapshot Release	release.yml	Changesets Snapshot mode
PR Feedback	prerelease-comment.yml	GitHub Script, Sticky Comments
Template Testing	templates.yml	Matrix testing, multi-pkg managers
Lockfile Sync	changeset-version.js	pnpm install --lockfile-only

Sources: .github/workflows/release.yml1-178 .github/workflows/templates.yml1-100 .github/changeset-version.js1-13