v4 registry catalog and build pipeline
Overview
The v4 registry catalog is split between authored registry source, generated lookup metadata, helper APIs used by the docs site, and scripts that export installable artifacts.
Authored local registry source lives under apps/v4/registry/. apps/…/bases.ts declares the base families (base, aria, and radix) with package dependencies and logo metadata. Each base has a registry.ts such as apps/…/registry.ts that validates a Registry object by parsing the combined ui, examples, lib, components, blocks, hooks, internal, and shared fonts item arrays with registryItemSchema.array(). Item arrays are stored beside their source files in _registry.ts files, for example apps/…/_registry.ts, apps/…/_registry.ts, and apps/…/_registry.ts. These entries are the package/install metadata: item name, registry type, package dependencies, registry dependencies, files, targets, categories, and links. Component, hook, lib, example, block, and internal source files sit in sibling directories named by their registry type.
apps/…/registry.ts is the committed legacy source registry. It builds a shadcn/ui registry from new-york-v4 ui, blocks, charts, lib, hooks, examples, and internal arrays plus legacy themes from apps/…/_legacy-themes.ts, and it filters the deprecated toast items before schema validation. Unlike generated base/style combinations, files under apps/v4/registry/new-york-v4/** are authored directly and committed.
Styles and design-system options are separate catalog layers. apps/…/styles.tsx lists named style tokens (vega, nova, maia, lyra, mira, luma, sera, rhea) and their UI metadata, while the CSS token maps live in apps/…/style-*.css. apps/…/themes.ts contains registry:theme items with light/dark OKLCH CSS variables; apps/…/base-colors.ts selects the base-color subset from those themes. apps/…/fonts.ts derives registry:font body and heading items from apps/…/font-definitions.ts, using the registry variables --font-sans, --font-mono, --font-serif, and --font-heading. apps/…/config.ts ties these pieces together: designSystemConfigSchema validates base/style/theme/font/menu/radius/template choices, DEFAULT_CONFIG and PRESETS provide preset combinations, buildThemeForPreset() emits a registry:theme item, buildRegistryBase() emits a full registry:base item with dependencies, registry dependencies, CSS imports, base vars, icon library config, RTL docs, and pointer cursor settings, and buildPartialRegistryBase() emits theme/font-only base updates.
Generated lookup files are committed under apps/v4/registry/ but are explicitly produced by apps/v4/scripts/build-registry.mts. apps/…/__index__.tsx maps base name to registry item metadata for authored base registries. apps/…/__index__.tsx maps final style id to registry item metadata for new-york-v4, legacy style ids from apps/…/_legacy-styles.ts, and every generated base/style combination. apps/…/__blocks__.json is the block metadata index read by block listing flows. The build script also writes generated component shard directories registry/__components__/ and registry/bases/__components__/ so metadata consumers can import index objects without pulling thousands of dynamic component imports into every route.
Runtime helper APIs in apps/…/registry.ts read those generated indexes for the docs site. getRegistryItem(name, styleName) looks up an item in apps/…/__index__.tsx, falling back to the base index from apps/…/__index__.tsx when the style name starts with a base prefix. It validates item metadata with registryItemSchema, reads referenced files from disk, rewrites default exports to named exports for non-page files, normalizes @/registry/... imports through fixImport(), computes install targets such as components/ui/<file>, hooks/<file>, or lib/<file>, rewrites file paths relative to the first file directory, and caches results for five minutes in an LRU cache. getRegistryItems() bulk-loads filtered items. getRegistryComponent() first tries demo components from the generated examples index, then lazy component shards from registry/__components__ and registry/bases/__components__. getDemoItem() wraps a demo source file as a registry:internal item. createFileTreeForRegistryItemFiles() converts installed targets into a display tree.
Other site-facing helpers expose registry metadata slices. apps/…/blocks.ts dynamically imports registry/__index__, merges block/internal items from apps/…/registry.ts, apps/…/registry.ts, and generated style indexes, validates each item with registryItemSchema, filters by type/category, excludes chart-*, and returns block ids or block items. apps/…/components.ts is the canonical UI component slug list used by registry-facing UI. apps/…/categories.ts defines block category labels and hidden flags. apps/…/themes.ts exposes non-neutral/stone/gray/zinc legacy base colors as themes. apps/…/colors.ts parses legacy Tailwind color palettes from apps/…/_legacy-colors.ts, normalizes RGB/HSL/OKLCH strings, computes foreground contrast, and exposes color-format metadata. apps/…/fonts.ts loads Next Google fonts and exports combined CSS variables for the app shell.
apps/…/registry.json is a static registry manifest for the v4 app. It follows the same item schema shape as the authored registries and points items to registry/new-york-v4/... paths, but the active build pipeline primarily consumes apps/…/registry.ts and generated public/r outputs.
The single registry build pipeline is apps/v4/scripts/build-registry.mts. A full build runs in this order: generate registry/…/__index__.tsx; create temporary styled registries under registry/<base>-<style> by applying shadcn/utils transformStyle() and icon transforms to authored base sources; generate registry/__index__.tsx; generate examples/__index__.tsx; export public/r/styles/<style> by writing a temporary registry-<style>.json and invoking ../../packages/shadcn/dist/index.js build; write registry/__blocks__.json; write public/…/config.json from presets; write public/…/index.json by merging base UI metadata and per-base docs links; write public/…/<baseColor>.json; copy compiled UI from temporary registries into styles/<style>/ui; generate RTL copies in styles/<style>/ui-rtl for base-nova, radix-nova, and aria-nova; then remove temporary registries and registry-<style>.json. The script supports fast targeted modes: --examples, --indexes, --style <style|all>, and --registry <style|all>. Targeted builds deliberately skip Prettier for speed; a full build re-canonicalizes generated output. The transform cache under node_modules/.cache/build-registry hashes the build implementation, shadcn/utils, the lockfile, authored registry files excluding generated indexes/component shards, and style CSS.
Build-adjacent scripts cover validation, screenshots, icons, and test apps. apps/v4/scripts/validate-registries.mts validates apps/…/directory.json against apps/…/registry-directory.ts and verifies that createPublicRegistryDirectory() produces the public four-field payload for /r/registries.json. apps/v4/scripts/capture-registry.mts uses Puppeteer against http://localhost:4000/view/<block> and getAllBlockIds() to capture missing light/dark block screenshots under public/r/styles/new-york/. apps/v4/scripts/capture-explore.mts captures preview preset screenshots under public/presets from /preview/radix/preview?preset=..., using --force to recapture existing files. apps/…/build-icons.ts scans registry/…/*.tsx for IconPlaceholder usage, writes per-library icon export files under registry/icons, and writes the canonical-to-library mapping at public/…/index.json while preserving legacy mapping order from registry/…/legacy-mapping.json. apps/v4/scripts/build-test-app.mts populates an external ui-test-apps checkout by transforming base components, hooks, examples, and blocks for a chosen style and writing them into next-<base> test apps.
The public registry directory is authored in apps/…/directory.json. apps/…/registry-directory.ts validates namespace format (@...), required homepage/logo/description, URL format with a {name} placeholder, and case-insensitive duplicate names. It also strips private logo/author fields from the public directory payload and normalizes registry names for search/comparison. Registry health monitoring for that directory is implemented under apps/v4/lib/registry-health/** and orchestrated by apps/v4/scripts/monitor-registries.mts: the prepare phase loads previous private state from Vercel Blob, the check phase runs without Blob credentials and calls runRegistryMonitor(), and the publish phase writes state, latest snapshot, run documents, and daily documents back to Blob and cleans expired history. apps/…/network.ts fetches registry JSON with SSRF guards, timeouts, redirect limits, content-size limits, and bot-challenge detection. apps/…/monitor.ts checks index availability/schema/name hygiene, samples item JSON validation, and schedules CLI dry runs through apps/…/dry-run.ts, which creates a temporary app and runs the local shadcn CLI with --dry-run. apps/…/score.ts computes score/status from availability, schema, item validity, dry-run, and hygiene signals, and apps/…/directory.ts merges fresh health/ranking overlays into a sorted, paginated directory view.
Coupling
- If an item is added, renamed, or removed in any _registry.ts file under
apps/v4/registry/**, also run the relevantapps/v4/scripts/build-registry.mtstarget. Metadata-only changes need--indexesfor registry/__index__.tsx, registry/…/__index__.tsx, registry/__blocks__.json, and public/…/index.json; install output changes need--registry <style|all>; generated style file changes need--style <base-style|all>. - If files listed in registry item
filesarrays move, update both the _registry.ts entry and the generated lookup/install artifacts. apps/…/registry.ts reads file paths from generated indexes and fails closed tonullwhenregistryItemSchemavalidation or file reads fail, so stale paths silently remove docs-site item payloads. - If apps/…/styles.tsx, apps/…/style-*.css, or apps/…/bases.ts changes, verify
apps/v4/scripts/build-registry.mtsstyle targeting and cleanup behavior. Generated style ids are the cross product ofBASESandSTYLES, and the build script treats legacy styles from apps/…/_legacy-styles.ts differently from generated combinations. - If font definitions change in apps/…/font-definitions.ts, verify apps/…/fonts.ts, apps/…/config.ts, and
apps/v4/scripts/build-registry.mtslegacy-font injection. Generated base registries include font items directly, whilebuildRegistryJsonFile()injects missing shared font items for legacy source registries such asnew-york-v4. - If apps/…/config.ts changes design-system config fields, update any consumers that encode/decode presets and the public/…/config.json build.
buildRegistryBase()andbuildPartialRegistryBase()turn validated config into installableregistry:basedependencies, registry dependencies, CSS vars, and CLI config. - If the schema in apps/…/registry-directory.ts changes, also check
apps/v4/scripts/validate-registries.mts,apps/v4/scripts/monitor-registries.mts, and apps/…/directory.ts. The validator, monitor, and public directory view all parse the same directory entries and assume public payloads are derived withcreatePublicRegistryDirectory(). - If apps/…/schema.ts increments versions or changes observation fields, verify apps/…/monitor.ts, score.ts, blob.ts, dry-run.ts, and
apps/v4/scripts/monitor-registries.mts. The monitor persists private state in Vercel Blob and only discards old dry-run/item history when version fields tell it to. - If
IconPlaceholdersyntax or icon libraries change, update apps/…/build-icons.ts and the build-time icon transforms inapps/v4/scripts/build-registry.mtsandapps/v4/scripts/build-test-app.mts. The icon script depends on a regex over registry/…/*.tsx, while the build scripts useshadcn/utilstransforms over TS ASTs.
Risks
apps/v4/scripts/build-registry.mtsintentionally skips formatting in targeted builds (runTargetedBuild()setsshouldFormatOutput = false). If a targeted build output is committed without a later fullpnpm registry:build, generated indexes or style files can carry avoidable formatting churn and obscure real registry changes.apps/v4/scripts/build-registry.mtshas separate handling for generated base/style combinations and legacy source registries. IfcleanUpTemporaryFiles()orrunTargetedStyleBuild()treatsnew-york-v4like a generated combination, it can delete authored source underapps/v4/registry/new-york-v4/**or reject the wrong build target.- apps/…/registry.ts rewrites imports and targets with regex/string rules in
fixImport()andgetFileTarget(). If authored registry files introduce import shapes outside those patterns, docs-site code previews and install payloads can keep@/registry/...paths or wrong targets instead of@/components,@/components/ui,@/hooks, or@/lib. - apps/…/network.ts is the SSRF boundary for third-party registry checks. If URL validation, DNS resolution, redirect handling, or guarded connector behavior is relaxed, scheduled health checks can reach private or local network addresses because
apps/v4/scripts/monitor-registries.mtsreads arbitrary contributor URLs from apps/…/directory.json. apps/v4/scripts/monitor-registries.mtsdeliberately strips Blob credentials from the check phase. IfBLOB_READ_WRITE_TOKEN,VERCEL_OIDC_TOKEN, orBLOB_STORE_IDare left in that phase environment, contributor registry fetches and CLI dry-run subprocesses run with unnecessary private Blob access.