Registry Core Resolution
Overview
The registry package published as @shadcn/registry is configured by packages/…/package.json to export the public API from packages/…/index.ts, the schemas from packages/…/index.ts, and internal modules through @shadcn/registry/internal/*. The build in packages/…/tsup.config.ts emits every non-test TypeScript file as an ESM entry so downstream callers can import internals while still sharing bundled chunks; packages/…/vitest.alias.ts points tests at source files rather than built output.
Registry addresses are normalized first. packages/…/address.ts classifies an input as a direct URL, local .json file, namespaced item, GitHub item, or default @shadcn item. Namespaced strings are parsed by packages/…/parser.ts using the @namespace/item form. GitHub source strings use owner/repo#ref for catalogs and owner/repo/item#ref for items; owner, repo, and ref validation rejects malformed owners, ./.. repos, empty refs, whitespace/control characters, and refs beginning with - before any fetch is attempted.
Registry configuration is defined in packages/…/schema.ts. registryConfigSchema accepts names beginning with @ and values either as URL templates containing {name} or objects with url, optional query params, and optional headers. packages/…/constants.ts provides the built-in @shadcn registry template at ${REGISTRY_URL}/…/{name}.json, with new-york-v4 as the fallback style. packages/…/config.ts merges caller config with those built-ins and upgrades new-york plus an empty Tailwind config to new-york-v4.
The API entry points in packages/…/api.ts wrap most network operations in withRegistryContext from packages/…/context.ts. That async-local context carries per-URL auth headers, optional environment overrides, and a GitHub-auth notice hook. getRegistry() loads a registry catalog from a direct URL, a GitHub source, or a configured namespace; namespace catalogs append /registry when needed and call buildUrlAndHeadersForRegistryItem() from packages/…/builder.ts. getRegistryItems() fetches item JSON, and resolveRegistryItems() returns a merged install tree. getRegistriesConfig() reads package.json registries via packages/…/json-config.ts, then merges components.json registries over package registries and built-ins when a components file exists.
URL and header construction happens in packages/…/builder.ts. A plain component name is routed through @shadcn; direct URLs, local paths, and GitHub item addresses bypass registry templates. Template expansion replaces {name} and optionally {style}, expands ${ENV_VAR} placeholders through packages/…/env.ts, appends expanded non-empty query params, and drops header values that expand to an empty value. packages/…/validator.ts preflights registry configs by extracting every ${VAR} reference from URL, params, and headers and throwing RegistryMissingEnvironmentVariablesError if any are unavailable in the registry context or process.env.
Fetching remote item JSON is centralized in packages/…/fetcher.ts. fetchRegistry() resolves relative registry paths against REGISTRY_URL, looks up headers registered in packages/…/context.ts, and caches promises by URL plus a SHA-256 hash of normalized headers. Requests set Accept: application/vnd.shadcn.v1+json, application/json;q=0.9 and User-Agent: shadcn; non-OK responses are mapped to typed registry errors, with JSON detail, message, and error fields included when present. Local item files are read by fetchRegistryLocal(), which expands ~/, parses JSON, and validates against registryItemSchema.
Proxy behavior lives in packages/…/proxy.ts. fetchWithProxy() installs an Undici dispatcher derived from ALL_PROXY SOCKS values or HTTP(S) proxy env vars, follows redirects manually for up to five hops, and only preserves caller-supplied headers across same-origin redirects. Cross-origin redirects retain only Accept and User-Agent, so custom private-registry secrets do not leak to a new origin.
GitHub registries are treated as source registries, not as prebuilt HTTP catalogs. packages/…/github-ref.ts resolves refs to SHAs with git ls-remote --symref --, preferring branches over tags for shorthand refs and caching by owner/repo#ref; if the git probe fails and an auth anchor is available, it falls back to authenticated resolution in packages/…/github-cli.ts. packages/…/github.ts then creates a RegistrySourceReader that reads registry.json and item files from raw GitHub URLs, the GitHub REST API with GH_TOKEN/GITHUB_TOKEN, or the gh CLI. packages/…/github-auth.ts coordinates the one-time choice of token versus gh per source cache and prints or reports a single auth notice. GitHub file reads are capped at 5 MiB in github-cli.ts, and authenticated 404s preserve the original anonymous failure for private-versus-missing ambiguity.
Source registry loading has two implementations for two storage backends. packages/…/loader.ts reads local filesystem registry.json files for loadRegistry() and loadRegistryItem(). packages/…/source.ts performs the same include flattening and item materialization through a generic RegistrySourceReader for GitHub-backed sources. Both parse chunks with registryChunkSchema, require the root registry to define name and homepage, support include trees up to depth 32, reject include cycles and duplicate includes, and ensure item names are unique after flattening. Includes must be relative paths ending in registry.json, cannot be remote or absolute, cannot traverse through .., and must stay inside the source root. Item file paths are similarly constrained to local relative paths inside the registry chunk directory.
When a catalog is loaded from source, loader.ts and source.ts rewrite each file path so consumers see paths relative to the source registry root and strip file content. When a single item is loaded, they read every referenced file, attach content, add the registry-item $schema, and validate the result with registryItemSchema. Consumer-facing remote catalogs loaded by getRegistry() in api.ts must already be resolved; if a served catalog still contains include, parseRegistryCatalog() throws and tells callers to run the build step or use loadRegistry() in a dynamic route.
Item resolution is orchestrated by packages/…/resolver.ts. fetchRegistryItems() handles GitHub addresses, local files, direct URLs, configured @namespace/item names, and default shadcn style paths. resolveRegistryTree() de-duplicates top-level names, fetches items, records each item's source, recursively resolves registryDependencies, and throws RegistryNotConfiguredError when a namespaced dependency appears without matching config. Non-namespaced dependencies are resolved through the shadcn index and the target style, while namespaced dependencies are fetched directly so their auth headers are registered. The final tree is topologically sorted by registryDependencies, theme items are moved first, Tailwind config, CSS vars, CSS objects, environment variables, docs, dependencies, and devDependencies are deep-merged, and files are de-duplicated by resolved target path through packages/…/utils.ts.
Search is implemented in packages/…/search.ts. resolveSearchRegistries() defaults an empty registry list to user-configured registries only, excluding built-ins. searchRegistries() fetches catalogs with concurrency capped at eight, forwards q, type, limit, and offset query params so dynamic registries can filter server-side, and locally fuzzy-searches static catalog items with fuzzysort over name, title, and description. A single dynamic registry returns its server pagination verbatim; multi-registry searches over-fetch each registry enough to compose a local page and can optionally record per-registry failures in the returned errors array. Search result formatting uses packages/…/highlighter.ts and packages/…/logger.ts for colored output.
Validation has a throwing loader path and a diagnostic path. The throwing path in loader.ts/source.ts is used while actually reading or serving registries. packages/…/validate.ts powers validation reports: it reads as many registry files and item files as possible, accumulates diagnostics with registry file, item name/index, include path, or file path, and returns counts plus a valid boolean instead of failing on the first issue. GitHub validation in github.ts reuses source loading and then validates each item with a concurrency cap of eight, translating registry errors into GitHub source diagnostics.
Errors are typed in packages/…/errors.ts, all extending RegistryError with a stable code, optional status, context, suggestion, timestamp, and JSON representation. The public barrel in index.ts exports these error classes along with API, loading, search, and add helpers. packages/…/logger.ts, packages/…/highlighter.ts, and packages/…/spinner.ts provide small reporting primitives, including logAboveSpinner() for GitHub auth notices while an Ora spinner is active.
Coupling
- If registry item or catalog fields change in packages/…/schema.ts, also update the public JSON schema mentioned in its file comment (apps/…/registry-item.json) and re-check packages/…/index.ts; the package export
./schemais just a re-export of the registry schema module. - If URL template semantics change in packages/…/builder.ts, also verify packages/…/validator.ts, packages/…/env.ts, and packages/…/api.ts; validation extracts env vars before fetches, while API header registration keys must match the final URL after search params are appended.
- If include or item-file path rules change in packages/…/loader.ts, mirror the same rule in packages/…/source.ts and packages/…/validate.ts; local builds, GitHub source reads, and diagnostic validation intentionally enforce the same constraints through separate implementations.
- If GitHub ref or content fetching changes in packages/…/github.ts, verify packages/…/github-ref.ts, packages/…/github-cli.ts, and packages/…/github-auth.ts; ref resolution, auth-mode selection, and raw/REST/gh content reads share the same source cache and error-preservation behavior.
- If
fetchWithProxy()in packages/…/proxy.ts changes redirect handling, check private registry and GitHub fetch callers in packages/…/fetcher.ts, packages/…/github.ts, and packages/…/github-cli.ts; those callers may attach credentials in arbitrary headers, and cross-origin redirect stripping is the guard against leaking them. - If search pagination or dynamic search parameters change in packages/…/search.ts, also check
getRegistry()in packages/…/api.ts; onlygetRegistry()appends the query params that dynamic registries see, while search.ts decides when local pagination is still needed. - If package exports or build entry rules change in packages/…/package.json or packages/…/tsup.config.ts, update packages/…/vitest.alias.ts; tests outside this package rely on the aliases to mock the same source modules that runtime registry code imports.
Risks
- packages/…/tsup.config.ts has a recent fix commit (
596be8dd fix(registry): stop emitting an empty chunk that crashes pnpm dlx on Windows (#12148)) guarding against ESM files with no import/export syntax. If new barrel-only modules or entry rules bypassassertModuleSyntax(), Windowspnpm dlxinstalls can load a chunk as CommonJS and hitERR_REQUIRE_CYCLE_MODULE. - packages/…/loader.ts, packages/…/source.ts, and packages/…/validate.ts duplicate include flattening and path-safety logic. If one implementation changes without the others, a registry can validate successfully but fail at build/runtime, or GitHub source registries can accept paths local source registries reject.
- packages/…/context.ts has a process-level fallback context for calls that do not use
withRegistryContext(). If a caller usessetRegistryHeaders()outside a scoped context, headers can persist into later fetches untilclearRegistryContext()runs, causing the wrong credentials to be sent for a matching URL. - packages/…/resolver.ts intentionally allows multiple items with the same
namefrom different sources and computes dependency ordering with source-derived hashes. If dependency strings are normalized differently from_sourcevalues, dependencies with duplicate names can attach to the first matching item and install in the wrong order.