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 / registry-install-updaters

Registry Install Updaters

Overview

The registry installation flow is orchestrated by packages/…/add-components.ts. addComponents() accepts component names plus a resolved project config, detects whether the current project is part of a workspace via getWorkspaceConfig(), and then delegates to either the single-project path (addProjectComponents()) or the workspace path (addWorkspaceComponents()). Both paths first call resolveAndValidateRegistryTree(), which either uses an already-provided resolved tree or calls resolveRegistryTree() with configWithDefaults(config), then rejects unsafe registry-controlled file paths through validateFilesTarget() before any writes happen.

For a normal project, addProjectComponents() turns the resolved registry tree into mutations in a fixed order: dependency installation, Tailwind config edits, .env updates, font setup, component file writes, and finally CSS writes. Fonts are prepared before most writes by massageTreeForFonts() in packages/…/update-fonts.ts: for Next.js projects it adds theme CSS variables that point to next/font variables; for other frameworks it adds @fontsource-variable/* dependencies, @import CSS entries, and theme variables. CSS is deliberately written last in add-components.ts so file watchers rebuild after files and dependencies are already in place.

Workspace installs in addWorkspaceComponents() use the same registry tree but split side effects across configs. Global dependency, Tailwind, env, and CSS changes go to workspaceConfig.ui, while fonts still use the app config because Next layout files live in the app. Registry files are grouped by an alias key derived from file.target, file.type, or the default components target, then updateFiles() is called once per target config. The workspace path tracks created, updated, and skipped files relative to the relevant workspace root and reports all results after a root spinner completes.

packages/…/update-dependencies.ts installs tree.dependencies and tree.devDependencies. updateDependencies() reads package.json from config.resolvedPaths.cwd, picks the package manager (using expo install when an Expo dependency is present), normalizes requests so bare already-installed package names do not rewrite existing ranges, and then invokes the package manager with execa. npm installs add --no-audit and --no-fund; React 19 plus react-day-picker@8 can prompt for --force or --legacy-peer-deps, defaulting to --force in silent or non-interactive mode. Dependency strings that begin with - are rejected before non-Deno package-manager calls to avoid argument injection.

packages/…/update-tailwind-config.ts applies tree.tailwind?.config for Tailwind v3 projects only; Tailwind v4 returns without touching a config file. The updater reads config.resolvedPaths.tailwindConfig, finds the first object expression with a content property, ensures darkMode includes "class", appends missing plugin expressions, and deep-merges theme additions while preserving spread syntax by temporarily stringifying spreads. If parsing or edits would leave syntax errors, the file is left unchanged and the function returns a warning string so callers can surface manual follow-up.

packages/…/update-env-vars.ts applies tree.envVars to the project root environment file. It prefers an existing env file found under config.resolvedPaths.cwd, otherwise creates .env.local, formats registry values as KEY=value, and uses env helper merging so only new keys are appended. packages/…/update-files.ts also has special handling for registry files that resolve to env paths: if an env file already exists, it merges only new keys instead of overwriting the file or running code transforms.

packages/…/update-fonts.ts has two roles. massageTreeForFonts() mutates the resolved registry tree before installation so font registry items also generate dependency, CSS import, theme-variable, and @layer base utility-class updates. updateFonts() then only edits Next.js app layouts: it locates app/layout.tsx|jsx or src/app/layout.tsx|jsx, adds or updates next/font/google imports and font variable declarations, and ensures the <html> className includes the new font variables and root font utility class through cn(). If the layout is unparsable or the generated edit introduces syntax errors, the updater skips writing and returns a warning.

packages/…/update-files.ts writes tree.files. It resolves each registry file to a target path through resolveFilePath(), taking src directory detection, framework, common root, CLI path, and file index into account. It converts TypeScript extensions to JavaScript when config.tsx is false, redirects missing env targets to an existing env file in the target directory, prevents writes over directories, and skips Laravel registry:lib utils.ts overwrites. Non-env and non-universal registry files run through the transformer pipeline for imports, RSC, CSS variables, Tailwind prefixes, icons, menu, asChild, RTL, Next 16 middleware/proxy handling, fonts, and cleanup. Existing files are skipped when transformed content is identical, prompted unless overwrite is set, and omitted automatically in non-interactive mode. After writes, resolveImports() rewrites alias imports in affected code files against the planned installed file set so generated imports match the user's configured aliases or package imports.

packages/…/update-css.ts writes the final stylesheet at config.resolvedPaths.tailwindCss. It first delegates CSS variable changes to transformCssVars() from packages/…/update-css-vars.ts, then merges tree.css entries with PostCSS. The CSS merger inserts missing @import rules at the top, @plugin rules after imports or existing plugins, empty at-rules with semicolons, keyframes under @theme inline, Tailwind v4-style @utility rules, nested at-rules, nested selectors, declarations, and merged @apply values via twMerge.

packages/…/update-css-vars.ts supports both direct updateCssVars() calls and the CSS phase in updateCss(). For Tailwind v3, variables are placed under @layer base with light mapped to :root and other keys mapped to class selectors. For Tailwind v4, the plugin sequence adds a dark custom variant, optionally removes default Next styles, writes root/theme/class variables without overwriting existing variables unless overwriteCssVars is true, creates @theme inline color and radius aliases, and converts Tailwind config plugins, animation, and keyframes into CSS constructs. add-components.ts decides overwriteCssVars: explicit CLI option wins, otherwise registry items whose type is registry:theme, registry:style, registry:font, or registry:base overwrite theme variables while ordinary component installs preserve user-defined variables.

Preset support in this covered area is defined by packages/…/preset.ts. It does not directly mutate projects; instead it provides compact design-system configuration codes consumed by registry/init flows outside this file set. encodePreset() merges partial input with DEFAULT_PRESET_CONFIG, bit-packs ordered fields into a safe JavaScript integer using multiplication rather than bitwise operators, and emits the current b version plus base62 data. decodePreset() accepts legacy a codes (without chartColor or fontHeading) and current b codes, fills out-of-range field indexes with defaults, and defaults legacy heading fonts to inherit. parsePresetStyle() separates an optional preset base prefix such as radix-, base-, or aria- from the style name so consumers can route preset installation by base and style.

Coupling

  • If registry schema fields for file paths, targets, dependencies, Tailwind, CSS, fonts, or env vars change, verify packages/…/add-components.ts and the matching updater in packages/registry/src/updaters/: add-components.ts assumes the resolved tree exposes dependencies, devDependencies, tailwind.config, envVars, fonts, files, css, cssVars, and docs and passes those shapes directly to updater functions.
  • If path resolution changes in the resolver layer used by packages/…/update-files.ts, also verify validateFilesTarget() in packages/…/add-components.ts: safety validation checks the registry-controlled target or path before writes, while updateFiles() later resolves the final target with framework and alias context.
  • If file target aliases or registry file types change, update the workspace grouping in packages/…/add-components.ts: addWorkspaceComponents() maps registry:ui, registry:hook, and registry:lib plus file.target aliases to workspace configs, and a missing mapping sends files to the default components target or app config.
  • If Tailwind v4 behavior changes, check both packages/…/update-tailwind-config.ts and packages/…/update-css-vars.ts: v4 skips JS config edits entirely, so plugins, animations, keyframes, variables, and theme aliases from registry Tailwind config must be represented in CSS during transformCssVars().
  • If font registry item semantics change, verify both phases in packages/…/update-fonts.ts and the CSS/file phases in packages/…/add-components.ts: massageTreeForFonts() mutates dependencies, CSS, and CSS variables before updateDependencies() and updateCss(), while updateFonts() separately edits Next layouts.
  • If import alias behavior changes, verify packages/…/update-files.ts: generated files are first transformed with canonical registry imports, then resolveImports() rewrites installed files based on tsconfig-paths, configured aliases, package imports, and the full planned file set.
  • If preset values are added in packages/…/preset.ts, append only to existing arrays and append new fields only at the end of PRESET_FIELDS_V2; decoding depends on stable field order, default-at-index-zero semantics, and staying below the 53-bit safe integer limit documented in that file.

Risks

  • packages/…/update-tailwind-config.ts intentionally leaves Tailwind config files unchanged when Babel cannot parse them or when an edit would introduce syntax errors. If a registry item relies on required plugins or theme keys, installation can appear successful while those Tailwind additions must be applied manually from the warning.
  • packages/…/update-fonts.ts skips Next layout writes when the layout is unparsable or the className edit would create syntax errors. In that case CSS variables and dependencies may still be installed, but the next/font variable class is not added to <html>, so the selected font may not take effect until the user edits the layout manually.
  • packages/…/update-files.ts prompts or skips existing non-env files unless overwrite is set. In non-interactive installs, conflicting component files are skipped automatically, which can leave new CSS, dependencies, or env variables installed without the corresponding component source update.
  • packages/…/preset.ts encodes presets by positional indexes rather than names. Reordering arrays such as PRESET_STYLES, PRESET_THEMES, PRESET_FONTS, or PRESET_FIELDS_V2 would silently decode existing preset URLs into different design settings.