Introducing a new way to review your PRs.

Read the announcement

shadcn-ui / ui

Composable, accessible components with thoughtful defaults. Build your own component library with code you can customize, extend, and make your own.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / repo-templates-tests-infrastructure

Repository templates, tests, and infrastructure

Overview

The repository is a pnpm/Turbo monorepo rooted at package.json and pnpm-workspace.yaml. The root workspace includes apps/* and packages/*, while explicitly excluding nested test, fixtures, and temp trees so fixture projects under packages/tests/fixtures/** and package-owned test fixtures are not treated as real workspaces. package.json pins pnpm 10.33.4, exposes root orchestration scripts, and routes most work through Turbo: build, lint, typecheck, format:*, dev, and registry health tasks. turbo.json defines the shared task graph, with package builds depending on upstream builds, lint/test tasks uncached, and registry health tasks receiving Vercel Blob/OIDC-related environment via passThroughEnv.

Root TypeScript and test configuration is deliberately broad but excludes harnesses where appropriate. tsconfig.json is the shared strict base for package configs. vitest.config.ts wires vite-tsconfig-paths and registry source aliases, then excludes **/fixtures/**, **/templates/**, and **/packages/tests/** from normal package test discovery. vitest.workspace.ts adds packages/…/vitest.config.ts as a separate Vitest project so integration tests can run with longer timeouts, global setup, and a different fixture lifecycle.

Formatting and linting are centralized in prettier.config.cjs, .prettierignore, .eslintrc.json, .eslintignore, and .commitlintrc.json. Prettier sorts imports with @ianvs/prettier-plugin-sort-imports, applies Tailwind class ordering with prettier-plugin-tailwindcss, and points Tailwind stylesheet context at apps/…/globals.css. ESLint extends Next core web vitals, Turbo, Prettier, and Tailwind rules, ignores fixtures, disables @next/next/no-html-link-for-pages and Tailwind custom-class checks, and marks Tailwind class ordering as an error. Commitlint extends conventional commits, matching the contributor-facing guidance in CONTRIBUTING.md.

Release automation is Changesets-based. .changeset/config.json uses the GitHub changelog plugin for shadcn-ui/ui, publishes public packages from main, updates internal dependencies at patch level, and ignores private workspaces v4 and tests. RELEASING.md documents the four independently published packages (shadcn, @shadcn/registry, @shadcn/react, @shadcn/helpers) and the important exact-version relationship where shadcn pins @shadcn/registry. .github/…/release.yml creates stable Version PRs on pushes to main and publishes PR snapshots when a PR is labeled release: beta or release: rc; both paths build packages with pnpm build:packages. .github/changeset-version.js runs changeset version and then pnpm install --lockfile-only so the lockfile is included in version PRs. .github/changeset-publish.js publishes packages in phases so registry-dependent packages such as shadcn are held back until the pinned @shadcn/registry version is visible on npm and, for tagged releases, matches the registry source tag.

CI lives under .github/workflows/**. test.yml runs root pnpm test plus package-specific test jobs for @shadcn/react and @shadcn/helpers. code-check.yml runs the registry changeset guard, lint, format, and typecheck; the typecheck job builds publishable packages, checks shadcn public exports, and builds generated registry styles before running pnpm typecheck. browser-tests.yml installs Playwright Chromium and runs pnpm --filter=@shadcn/react test:browser for React package changes. validate-registries.yml is narrowly triggered by apps/…/directory.json, blocks reserved registry namespaces inline, then runs pnpm --filter=v4 validate:registries. monitor-registries.yml runs hourly or manually and maps to the root registry:health:* scripts. signed-commits.yml labels PRs with unsigned commits, and signed-commits-close.yml closes still-unsigned labeled PRs after 14 days.

The template fleet under templates/** is the source for CLI-created application scaffolds. There are app and monorepo variants for next, vite, astro, start (TanStack Start), and react-router. App templates such as templates/…/package.json, templates/…/package.json, templates/…/package.json, templates/…/package.json, and templates/…/package.json include framework-native dev/build/typecheck scripts, React 19-era dependencies, Tailwind v4 integration, and starter pages that import a generated shadcn Button (templates/…/page.tsx, templates/…/App.tsx, templates/…/index.tsx, templates/…/home.tsx). Monorepo templates such as templates/…/package.json, templates/…/package.json, and templates/…/package.json use Turbo, pnpm 11.25.0, apps/web, and packages/ui; their apps/…/components.json files route shared UI installs to @workspace/ui/components and utils to @workspace/ui/lib/utils, while the Tailwind CSS file points at ../…/globals.css. templates/…/components.json additionally sets iconLibrary to remixicon, rtl false, and menu styling defaults.

Template validation is split between local sync and CI generation. scripts/sync-templates.sh iterates over a glob (root script sync:templates passes templates/*), commits any pending monorepo template updates, clones the corresponding shadcn/<template-name> repository, wipes the clone except .git, copies the template contents, and pushes changes using the original commit message. .github/…/templates.yml validates each template (next, vite, astro, start, react-router) in app and monorepo modes across pnpm, bun, npm, and yarn. It builds the local CLI and registry first, stages a local shadcn package whose @shadcn/registry dependency points to a packed tarball for package managers that cannot consume workspace:, then creates projects through shadcn init with SHADCN_TEMPLATE_DIR pointed at templates. For pnpm projects it runs install, typecheck, and build; for non-pnpm projects it checks that pnpm workspace files were removed and that monorepo package metadata matches the selected package manager.

packages/tests/** is the integration harness for the shadcn CLI and is intentionally excluded from the root workspace globs while still referenced by vitest.workspace.ts. packages/…/package.json depends on the local shadcn workspace package and exposes test, format:*, and typecheck. packages/…/vitest.config.ts sets 120s test and hook timeouts, Node environment, globals, maxConcurrency: 4, isolate: false, and a global setup. packages/…/setup.ts creates packages/tests/temp, waits for packages/…/index.js and packages/…/index.js, warms the local v4 /init route and a first 404 route, then removes temp output after the run. packages/…/helpers.ts copies fixtures from packages/tests/fixtures/** into unique temp directories, runs the built CLI via node, injects REGISTRY_URL and SHADCN_TEMPLATE_DIR, and normalizes timeout failures into non-zero results. packages/…/registry.ts provides a lightweight HTTP registry fixture with built-in endpoints for registries.json, icons, colors, style indexes, registry indexes, item lookup, and bearer/API-key/client-secret/query-param auth variants.

The integration tests cover CLI flows rather than package-internal units. packages/…/init.test.ts exercises default init, CSS-variable toggles, component installation during init, custom aliases, custom style registry payloads, and template/monorepo initialization. packages/…/add.test.ts covers adding local, URL, registry-dependent, dependency-bearing, CSS-var, page, and multi-item registry entries against both the live local registry and file fixtures. packages/…/apply.test.ts verifies preset application, RTL handling, and monorepo preset config behavior. packages/…/registries.test.ts, view.test.ts, and search.test.ts use createRegistryServer plus fixture components.json registry maps to validate multi-registry resolution, viewing, and search. packages/…/mcp.test.ts starts the CLI mcp command through @modelcontextprotocol/client over stdio and verifies multiple protocol negotiation modes.

The skills/** tree is documentation and rule content for AI/agent workflows, not runtime code. skills/…/SKILL.md is the main shadcn skill: frontmatter declares trigger text and allowed shadcn command runners, then the body describes project-context lookup, component selection rules, styling/composition/form/icon/chat rules, CLI workflows, preset handling, and design-system workflow references. Supporting files such as skills/…/cli.md, skills/…/registry.md, skills/…/design-system.md, and skills/…/*.md provide deeper references for commands, source/built registries, DESIGN.md-to-app conversion, and component correctness rules. skills/…/showcase-coverage.mjs is a small Node checker that compares installed UI component filenames against imports in showcase directories and exits non-zero when any component is not shown. skills/…/SKILL.md and its reference markdown files describe a Radix-to-Base UI migration process, including golden-pair strategy, progressive versus whole-project modes, import/prop/data-attribute mappings, wrapper shapes, and report format.

Top-level docs are sparse but set repository expectations. README.md points users to documentation, contributing, and MIT licensing. CONTRIBUTING.md explains the monorepo structure, pnpm/Turbo/Changesets usage, local dev commands, registry build expectations, commit categories, CLI package ownership, and root pnpm test requirement. SECURITY.md directs vulnerability reports to GitHub private vulnerability reporting. LICENSE.md is the MIT license.

Coupling

Risks

  • scripts/sync-templates.sh can commit and push automatically. If it is run with an unexpected dirty tree or from the wrong branch, lines that call git add ., git commit, and git push origin main can publish unrelated changes before syncing templates.
  • scripts/sync-templates.sh deletes clone contents with find . | grep -v ".git" | grep -v "^\.*$" | xargs rm -rf before copying template files. If CLONE_DIR or BASE is wrong, the deletion/copy phase can corrupt the wrong directory or push a bad mirror to a read-only template repository.
  • packages/…/setup.ts assumes the Next dev server is ready after warming /init and a first 404. If route paths, query parameters, or local registry defaults change without updating this warm-up, the first CLI integration test can time out rather than fail at the actual behavior under test.
  • .github/changeset-publish.js rewrites publishable package manifests to mark registry-dependent packages private during the first publish phase, then restores them in finally. If this script exits outside that guarded block or package discovery changes, a release job can leave local package manifests in a temporary private state and publish only part of the intended release.