Registry Project Detection and Configuration
Overview
This area is the registry package's project-shape and path-resolution layer. It discovers framework, Tailwind, TypeScript, workspace, package-manager, environment, and alias information from a target directory, then turns registry item targets into concrete filesystem paths.
Framework metadata is centralized in packages/…/frameworks.ts. FRAMEWORKS maps internal framework keys such as next-app, next-pages, vite, react-router, laravel, expo, and manual to display labels plus installation and Tailwind guide URLs. packages/…/get-project-info.ts is the main detector: getProjectInfo(cwd) concurrently scans for framework config files, src/, TypeScript config files, Tailwind files, alias prefixes, and package.json. It then classifies the framework in a fixed priority order: Next.js config first, then Astro, Gatsby, Laravel, Remix dependencies, TanStack Start dependency, React Router config, Vite config, Vinxi-style app.config.* containing defineConfig, Expo dependency, and finally manual. For Next.js it also checks app or src/app to distinguish App Router from Pages Router and sets isRSC; getFrameworkVersion only extracts the Next package version.
Tailwind and TypeScript detection also live in packages/…/get-project-info.ts. getTailwindVersion(cwd) treats an existing config with tailwind.config === "" as Tailwind v4, returns null when no Tailwind dependency exists, recognizes v3 dependency ranges, and otherwise assumes v4. getTailwindCssFile(cwd, configCssFile) prefers an existing configured CSS file, then scans CSS/SCSS files for either @import "tailwindcss", @import 'tailwindcss', or @tailwind base; getTailwindConfigFile(cwd) scans for tailwind.config.*. isTypeScriptProject(cwd) checks for shallow tsconfig.* files. Alias prefix detection uses tsconfig-paths first, falling back to manually parsed tsconfig.json, tsconfig.web.json, or tsconfig.app.json via getTsConfig; the parser strips comments and trailing commas before validating compilerOptions.paths.
packages/…/get-config.ts loads and normalizes components.json. getRawConfig(cwd) searches with a JSON explorer for components.json, validates it against rawConfigSchema, and rejects attempts to override built-in registries. getConfig(cwd) applies the default icon library (radix for new-york, otherwise lucide) and calls resolveConfigPaths(cwd, config). resolveConfigPaths merges built-in registries, loads tsconfig/jsconfig with tsconfig-paths, resolves components, utils, ui, lib, and hooks aliases, and returns a parsed Config with absolute resolvedPaths. ui, lib, and hooks fall back relative to the resolved components or utils path when not configured. Alias resolution goes through resolveImportWithMetadata in packages/…/resolve-import.ts, so components.json aliases can be backed by tsconfig paths, package.json#imports, or workspace package exports.
When no components.json exists, getProjectConfig(cwd) in packages/…/get-project-info.ts builds a default config only if project info has enough evidence: a Tailwind CSS file, a Tailwind config file for v3, and an alias prefix. It derives standard aliases from the prefix (<prefix>/components, <prefix>/lib/utils, etc.), but if the prefix came from package.json#imports, it asks getPackageImportAliases(cwd) in packages/…/package-imports.ts for better component/ui/lib/hooks/utils aliases before passing the raw config through resolveConfigPaths.
Monorepo and workspace discovery is split between packages/…/get-monorepo-info.ts, packages/…/get-config.ts, and packages/…/workspace.ts. isMonorepoRoot(cwd) checks for pnpm-workspace.yaml, package.json workspaces, lerna.json, or nx.json. getWorkspacePatterns(cwd) extracts workspace globs from pnpm workspace YAML and npm/Yarn workspace declarations, ignoring negated package globs. getMonorepoTargets(cwd) expands those patterns to workspace directories containing package.json and either components.json or a framework config, returning whether each target already has registry config; formatMonorepoMessage prints shadcn <command> -c <workspace> suggestions. getWorkspaceConfig(config) detects aliases that resolve into another package root by finding package.json files near the alias path, then requires that workspace to have its own components.json.
Package imports and workspace exports share the normalized matcher in packages/…/import-matcher.ts. An ImportResolutionEntry records an alias key, alias base, local target, emit mode, wildcard flag, and root directory. resolveLocalPathTarget walks strings, arrays, and condition objects to find the first ./ target. getImportTargetEmitMode decides whether rewritten imports should strip or preserve extensions based on wildcard targets. resolveImportEntryMatch handles exact matches before wildcard matches, preferring longer wildcard keys, and uses getPatternWildcardValue plus applyWildcardTarget to produce local paths.
packages/…/package-imports.ts converts package.json#imports into matcher entries for keys beginning with #, caches them by cwd, resolves imports with resolvePackageImport, and computes a shared # prefix. getPackageImportAliases scores import entries to find likely components, ui, lib, hooks, and utils aliases, with root wildcard defaults for #*. packages/…/workspace.ts does the same for package.json#exports of sibling workspace packages: it climbs from the cwd to the nearest workspace root without crossing the git root, loads workspace package names from workspace globs, caches package/export metadata, parses bare and scoped package specifiers, and resolves exports like @workspace/ui/button to package-local targets. packages/…/resolve-import.ts tries package imports first for #..., then workspace package exports, then tsconfig paths; scoped package specifiers are rejected from the tsconfig fallback unless a tsconfig path pattern actually matched. isLocalAliasImport intentionally treats #... as local but does not treat workspace package exports as local alias imports, because those specifiers should remain final package imports.
Registry file placement is handled by packages/…/resolve-file-path.ts. resolveFilePath(file, config, options) honors a CLI/custom options.path first: if it points to a file-like last segment, only the first registry file uses it; if it points to a directory, every registry file is placed under that directory using the source basename. File target values beginning with ~/ resolve inside config.resolvedPaths.cwd. Targets of the form @components/..., @ui/..., @lib/..., or @hooks/... are recognized through packages/…/target-aliases.ts and resolved under the corresponding alias root; any path that escapes the alias root throws. Other @name/... targets are de-aliased to name/... and then placed under cwd, with src/ inserted or removed according to the project isSrcDir flag. Registry file types without an explicit target default to ui, lib, components, or hooks directories. resolvePageTarget maps registry:page targets from App Router shape into Next Pages, React Router, or Laravel page locations, and returns an empty path for unsupported frameworks.
Safety and environment helpers are small but sit on this same install-path boundary. packages/…/is-safe-target.ts rejects target paths with null bytes, malformed or repeated URL encoding, explicit .. traversal, control characters, unsafe ~/../ usage, Windows drive letters outside the project, and absolute or resolved relative paths outside cwd; it strips framework catch-all route segments like [...slug] before traversal checks. packages/…/env-loader.ts loads .env.local, .env.development.local, .env.development, then .env with @dotenvx/dotenvx, using overload: false so existing process env values win. packages/…/env-helpers.ts identifies .env* files, finds the first existing env file in the order .env.local, .env, .env.development.local, .env.development, parses simple KEY=value lines, reports new keys, and merges env content by appending only missing keys while preserving existing values.
Other covered helpers provide data consumed by registry item processing rather than project detection itself. packages/…/get-package-manager.ts uses @antfu/ni detection, normalizes yarn@berry and pnpm@6, optionally falls back to npm_config_user_agent, and maps package managers to runner commands (pnpm dlx, bunx, otherwise npx). packages/…/get-package-info.ts is the thin package.json reader used throughout detection. packages/…/tailwind-theme-colors.ts converts registry CSS variable keys into Tailwind theme.colors entries using hsl(var(--...)), creating nested color objects and removing synthetic DEFAULT values when the base variable was absent. packages/…/font-markers.ts maps supported font CSS variables, currently --font-heading, to marker class names from font declarations or CSS vars. packages/…/libraries.ts defines supported icon libraries, their install packages, import templates, JSX usage templates, and export modules. packages/…/index.ts exposes fixture-directory lookup, multi-file writes, and auto-cleaned temp directories for tests.
Coupling
- If
packages/registry/src/registry/schemachanges the shape ofrawConfigSchema,configSchema,workspaceConfigSchema, or registry item file fields, update packages/…/get-config.ts, packages/…/get-project-info.ts, and packages/…/resolve-file-path.ts together; these files parse raw config, synthesize default config, and consume resolved paths from the same schema contract. - If a new alias target key is added, update both packages/…/target-aliases.ts and the alias resolution/defaulting paths in packages/…/get-config.ts, packages/…/get-project-info.ts, and packages/…/resolve-file-path.ts; otherwise components.json may validate an alias that registry file targets cannot safely resolve, or vice versa.
- If
package.json#importsor workspaceexportsmatching changes in packages/…/import-matcher.ts, verify packages/…/package-imports.ts, packages/…/workspace.ts, and packages/…/resolve-import.ts; all three rely on the same wildcard, target, and extension-emission semantics to keep generated import specifiers aligned with file placement. - If framework identifiers in packages/…/frameworks.ts change, check packages/…/get-project-info.ts and packages/…/resolve-file-path.ts; framework names are used both for detection and for
registry:pagetarget rewriting. - If workspace pattern parsing in packages/…/get-monorepo-info.ts changes, verify packages/…/workspace.ts; workspace package export resolution uses the same patterns to find sibling package roots.
- If env file priority changes, check both packages/…/env-loader.ts and packages/…/env-helpers.ts; loading order and “which file should receive new keys” order are similar but not identical today.
Risks
- packages/…/is-safe-target.ts and packages/…/resolve-file-path.ts are the last line before writing registry files to disk. If either allows encoded traversal, alias-root escape, or unsafe absolute paths, a registry item can write outside the intended project root or alias directory.
- packages/…/get-project-info.ts calls
getTailwindVersion(cwd), andgetTailwindVersioncallsgetConfig(cwd), which can throw on invalid components.json. A malformed config can prevent otherwise independent project detection from completing. - packages/…/workspace.ts caches workspace roots, package maps, and export entries in process-wide maps. If tests or long-running commands mutate workspace package.json or
exportsafter the first lookup, import resolution can continue using stale workspace metadata.