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-transformers-codemod

Registry transformers and codemod utilities

Overview

The registry transformation layer rewrites registry item source before files are compared or written into a project. Its public orchestrator is packages/…/index.ts: transform(opts, transformers) strips a leading byte-order mark, runs a sequence of text transformers over opts.raw, and then either returns getTextFromFirstToken(code) or, when opts.transformJsx is true, returns transformJsx(code, opts). The default chain in index.ts is transformImport, transformRsc, transformCssVars, transformTwPrefixes, transformRtl, transformIcons, and transformCleanup; install/update callers can pass their own chain.

The main install/update invocation is packages/…/update-files.ts. updateFiles() skips this layer for .env, registry:file, and registry:item content, but otherwise calls transform() with registry content, config, fetched base color, remote flag, JSX output flag, and supported font markers. Its install chain is deliberately broader than the default: transformImport, transformRsc, transformCssVars, transformTwPrefixes, transformIcons, transformMenu, transformAsChild, transformRtl, conditional transformNext, transformFont, then transformCleanup. After transformation, update-files.ts uses rewriteResolvedImportsInContent() and packages/…/import-declarations.ts to rewrite planned local alias imports against the target project.

Most transformers are string-in/string-out functions over original source positions. packages/…/parse.ts supplies Babel-backed parsing shaped to mimic the old ts-morph/TypeScript behavior: parseModule() uses TypeScript and JSX plugins, error recovery, skipped-comma masking, and optional JSX parsing; parseTransformInput() returns undefined for inputs Babel still cannot parse so transformers can leave files untouched; parseMaskingLines() masks non-code lines so JSX in MDX-like files can still be found. The same file provides source-order traversal (getDescendants()), text slicing (getText()), and refinding edited nodes by start position (findNodeAt()). packages/…/source-text.ts preserves the old runner boundary by removing a BOM and returning text from TypeScript's first token, which drops leading trivia, shebangs, and leading conflict-marker trivia.

Source edits are centralized in packages/…/edits.ts. applyEdits() applies non-overlapping original-position edits from the end of the file; applyManipulation() additionally rejects edits that increase syntax errors, matching ts-morph's manipulation checks except for intentionally skipped object-literal commas. Helpers such as replaceWithText() and getTextEdit() let transformers compose edits without reparsing entire files after every change. Formatting fidelity comes from packages/…/indentation.ts, which rebuilds enough of TypeScript's syntax tree from Babel nodes to reproduce ts-morph indentation for multi-line replacements, object/array insertions, JSX attributes, and list entries.

The codemod package is a compatibility layer for common ts-morph operations:

  • packages/…/string-literals.ts tracks string/directive literals and no-substitution templates, reads values like TypeScript, handles JSX attribute entity behavior, and accumulates setLiteralValue()-style edits.
  • packages/…/jsx-attributes.ts finds JSX attributes in source order, removes attributes with surrounding trivia, and replaces attribute initializers with indentation-aware text.
  • packages/…/comma-lists.ts, array-literals.ts, and object-literals.ts implement comma-separated insertion/removal, comment-node-aware object member operations, array holes, JSDoc starts, and post-edit structural verification.
  • packages/…/statements.ts models source-file statements plus standalone comment nodes, removes statements with ts-morph spacing rules, and inserts import declarations after leading block comments and existing imports.
  • packages/…/named-imports.ts reads, adds, and removes named imports while preserving empty/default/side-effect import shapes.
  • packages/…/rename.ts renames function and variable bindings through Babel scope analysis while disabling Babel's collision checks to tolerate TypeScript-style redeclarations.
  • packages/…/trivia.ts, comment-nodes.ts, and variables.ts provide lower-level scanning for whitespace, comments, JSDoc, statement/object comment nodes, and variable initializer replacement.

Individual registry transformers are narrowly scoped:

  • packages/…/transform-import.ts rewrites registry and local alias import specifiers according to config.aliases, isRemote, and package-import forms such as #registry and #/.... It visits TypeScript's import string literal surface: top-level import/export declarations, import-equals, dynamic import(), import type, and ambient module specifiers when TypeScript would collect them. It special-cases cn from @/lib/utils so utility imports land on config.aliases.utils.
  • packages/…/transform-rsc.ts removes a top-level "use client" directive when config.rsc is false, using statement/comment-aware removal. It intentionally carries a module-level global regex state documented by its tests.
  • packages/…/transform-css-vars.ts inlines theme colors when config.tailwind.cssVariables is false and baseColor.inlineColors is present. It maps color-related Tailwind class strings across all string literals, adds dark variants, preserves alpha modifiers, and treats bare border as border border-border.
  • packages/…/transform-tw-prefix.ts applies Tailwind prefixes to strings found in cva() variants, className, classNames, and cn() calls. It branches on getProjectTailwindVersionFromConfig(): v3 prefixes the utility segment (hover:tw-bg...), while v4 prepends prefix: unless already present. applyPrefixesCss() performs the matching @apply rewrite for CSS text.
  • packages/…/transform-icons.ts replaces self-closing <IconPlaceholder ... /> elements with configured icon-library usage from iconLibraries, removes placeholder/library-specific props, updates imports, and supports MDX-like files by masking non-code lines when placeholders are present. It preserves ts-morph edge behavior for expression-provided icon names, forgotten nodes, and semicolon style.
  • packages/…/transform-menu.ts resolves cn-menu-target and cn-menu-translucent markers from config.menuColor, either replacing targets with dark, removing markers, or inlining a hardcoded translucent class bundle via twMerge().
  • packages/…/transform-aschild.ts runs only for base-* styles and converts leaf <Parent asChild><Child ...>...</Child></Parent> structures into render props. It iterates from inner elements outward, removes orphan asChild attributes, and adds nativeButton={false} for Button render props targeting non-button elements.
  • packages/…/transform-rtl.ts runs when config.rtl is true and also exposes transformDirection() for build-time RTL conversion. It rewrites physical Tailwind classes to logical classes, adds rtl: variants for translate/space/divide/cursor cases, replaces cn-rtl-flip, rewrites logical side animation variants, and changes selected menu side="left/right" props and defaults to inline-start/inline-end.
  • packages/…/transform-next.ts performs the Next.js 16 middleware migration. It renames top-level middleware function/variable declarations to proxy and edits named export specifiers such as export { handler as middleware }, leaving unparsable files untouched.
  • packages/…/transform-font.ts handles cn-font-heading. It checks support from config.resolvedPaths.tailwindCss by looking for --font-heading: and merges supportedFontMarkers; supported markers become font-heading, unsupported markers are removed. It edits JSX class attributes first, removes empty attributes, then reparses and rewrites cva() and mergeProps() strings.
  • packages/…/transform-cleanup.ts removes generic cn-* marker classes from JSX class attributes, cva() calls, and mergeProps() calls, while preserving cn-font-heading so transformFont can process it later. It exposes cleanupMarkers() for standalone build usage.
  • packages/…/transform-jsx.ts is the final JavaScript-output pass when config.tsx is false. It parses TSX with Recast and broad Babel syntax plugins, runs @babel/plugin-transform-typescript, and prints JavaScript while preserving formatting as much as Recast allows.

Tests and snapshots are part of the behavioral contract. packages/…/index.test.ts pins the orchestrator's text-boundary behavior, default transformer list, nested filenames, non-TS inputs, MDX icon behavior, and the distinction between normal output and transformJsx output. packages/…/transform-corpus.test.ts is the broad golden corpus: fixtures from real registry payloads are run through individual transformers, install chains, default chains, and JSX output, and snapshots record line diffs from input. The per-transformer tests and packages/…/*.test.ts files document edge cases in ts-morph compatibility, formatting, parse recovery, and marker-specific behavior.

Coupling

Risks