migrate-radix-to-base

Name: migrate-radix-to-base
Author: shadcn

byshadcn· 3 skills

Installs

10k

Stars

120k

Forks

9.5k

How to install migrate-radix-to-base?

shadcn/ui/migrate-radix-to-base

$npx -y skills add shadcn/ui --skill migrate-radix-to-base

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/shadcn/ui" --skill "shadcn/ui/migrate-radix-to-base"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/shadcn/ui" that are relevant to the current task. Run `npx skills add "https://github.com/shadcn/ui"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# Radix UI -> Base UI migration
2
3	You migrate shadcn wrappers, hand-rolled radix compositions, and their
4	consumers to `@base-ui/react`, keeping the project buildable at every step.
5	Be precise; never guess a mapping. When a prop or part is not in these
6	reference files, check `node_modules/@base-ui/react/*/.d.ts` before
7	transforming, and record gaps in the report.
8
9	## Preflight (always)
10
11	1. `npx shadcn@latest info --json` (or the project's runner): gives the
12	current base, STYLE (e.g. `radix-lyra`), tailwind version, aliases,
13	installed components, and package manager. Trust it over inference.
14	2. Detect the package manager (packageManager field / lockfile:
15	pnpm-lock.yaml, bun.lock, yarn.lock, package-lock.json) and use IT for
16	every install. Never leave a stale lockfile.
17	3. Require a clean git tree; work on a branch; one commit per component.
18	4. Baseline check BEFORE touching dependencies: run the project's
19	typecheck/build so pre-existing failures are never attributed to you.
20	5. Install `@base-ui/react` alongside radix. Radix packages are removed only
21	after the LAST component is migrated (both coexist fine).
22
23	## Strategy: golden pair first, transformation engine second
24
25	- Golden pair via the CLI (preferred). If the project is shadcn with a
26	known style (`radix-<style>`), the shadcn CLI itself is the golden-pair
27	executor:
28	1. Classify each ui wrapper FIRST: diff the user's file against its stock
29	origin, using the components.json style VERBATIM in the URL
30	(`https://ui.shadcn.com/r/styles/<style>/<component>.json`,
31	files[0].content). This works for prefixed styles (radix-nova) AND
32	legacy unprefixed ones (new-york, new-york-v4, default), which are all
33	still served.
34	2. WHOLE-PROJECT mode: flip `components.json` style `radix-<style>` ->
35	`base-<style>` now. PROGRESSIVE mode: do NOT flip yet (the project is
36	still mostly radix; the flip happens once, after the last component);
37	fetch base variants directly by URL instead
38	(`https://ui.shadcn.com/r/styles/base-<style>/<component>.json`).
39	3. PRISTINE wrappers, whole-project mode: `shadcn add <component>
40	--overwrite` delivers the base variant with the project's exact
41	icon/font/preset resolution. Never bulk `--all --overwrite`; go
42	component by component, or you drown in unrelated registry version
43	drift. PROGRESSIVE mode: never use `--overwrite` (it destroys the
44	original that consumers still import); write the fetched base variant
45	content to `<component>-base.tsx` instead.
46	4. CUSTOMIZED wrappers: fetch the base variant and replay the user's diff
47	onto it (their customizations must SURVIVE; `--overwrite` would destroy
48	them). Mechanical implementation that works at scale:
49	`git merge-file user.tsx radix-golden.tsx base-golden.tsx` (three-way
50	merge, radix golden as ancestor) auto-resolves most files; hand-resolve
51	conflicts with the reference tables.
52	5. MANDATORY leftover sweep on EVERY golden-pair file, including ones that
53	merged "clean": `grep -n "radix-ui\\|@radix-ui\\|IconPlaceholder"` per
54	file. The registry sometimes reorders functions between variants, which
55	makes three-way merges report zero conflicts while leaving stale radix
56	hunks in place. A clean merge is NOT proof of a clean file.
57	This is more reliable than reconstructing transforms; use it whenever the
58	pair exists. Consumer/app code has no CLI mechanism: always hand-migrate it
59	against `consumer-props.md`.
60	- **Legacy styles (new-york, new-york-v4, default): classification only, no
61	replay.** These have no base counterpart (there is no base-new-york), and
62	retargeting onto a base-<style> variant would restyle the user's app. Use
63	the radix golden ONLY to detect customizations, then run the transformation
64	engine on the user's OWN file: rewire primitives, keep their exact classes,
65	apply class-mapping renames. Their look stays theirs. At the end of a
66	legacy whole-project migration, FLAG (do not fix): the style name still
67	reads as radix to the CLI, so future `shadcn add` will deliver radix
68	variants; the user decides whether to switch style or add manually.
69	- Transformation engine (fallback). Hand-rolled radix code, non-shadcn
70	projects, unknown styles: transform using `universal-patterns.md` (imports
71	in BOTH forms: `radix-ui` and `@radix-ui/react-*`; asChild->render with the
72	worked example; Portal>Positioner>Popup; the positioner FORWARD rule; part
73	renames), the per-family props tables (`overlays.md`, `menus.md`,
74	`form-controls.md`, `disclosure.md`, `display-misc.md`), `class-mapping.md`
75	for data-attribute/CSS-var rewrites, and `wrapper-shapes.md` for exact
76	target shapes (tooltip arrow, SubContent defaults, select anatomy).
77
78	## Modes
79
80	Progressive (default). "Migrate accordion" = one component, strangler-fig:
81	1. Detect in-progress state first: an existing `<component>-base.tsx`,
82	consumers split between old/new imports. The files ARE the state; resume,
83	never restart.
84	2. If the component imports other ui wrappers still on radix (select ->
85	button), STOP and recommend migrating those first, bottom-up.
86	3. Write the migrated version to `<component>-base.tsx` (original untouched;
87	golden-pair content fetched by URL, or transformed by hand, per the
88	strategy above); typecheck. Repoint consumers ONE AT A TIME (imports + the
89	call-site props in `consumer-props.md`); typecheck each. When no consumer
90	imports the original: delete it, rename `-base` -> original, flip imports
91	back, final check, commit. When the LAST radix wrapper in the project is
92	finalized, flip `components.json` to `base-<style>` and remove radix deps.
93
94	Whole project (only when explicitly asked): same per-component work in
95	dependency order (leaf/shared wrappers like button and label first). After
96	wrappers, sweep ALL app code against `consumer-props.md` — the call-site
97	break surface is much larger than asChild. Then remove radix deps, install,
98	full build.
99
100	## Hard rules
101
102	- NEVER touch non-radix libraries or their wrappers: cmdk (command), vaul
103	(drawer), sonner, input-otp, react-day-picker (calendar), recharts (chart).
104	Report them as intentionally untouched.
105	- No Base UI counterpart: AspectRatio -> CSS aspect-ratio div; Label ->
106	native `<label>`; VisuallyHidden -> `sr-only`; Direction -> Direction
107	Provider (`direction` prop, not `dir`). Popover Anchor and NavigationMenu
108	Indicator have no equivalent: inert passthrough + flag.
109	- `button.tsx` migrates to the REAL `@base-ui/react/button` primitive, never
110	a hand-rolled useRender wrapper.
111	- Behavior deltas are FLAGGED, never silently patched (tabs manual
112	activation, menu items not closing on click, nav-menu 50ms delay). The
113	target is idiomatic Base UI matching the shadcn base registry.
114	- Honest reporting: skipped/reverted files are listed as flagged, never as
115	migrated. Pre-existing failures are named as pre-existing.
116
117	## Verify and report
118
119	Typecheck per file, build per batch, full build at the end vs the baseline.
120
121	Reports live in a `.migration/` directory at the project root, ONE FILE PER
122	COMPONENT: `.migration/<component>.md` (e.g. `.migration/accordion.md`).
123	Rules:
124	- Each run writes (or fully overwrites) the file for each component it
125	migrated. Re-running a component replaces its report; never touch other
126	components' files.
127	- A multi-component run ("migrate alert-dialog and dropdown-menu") writes one
128	file per component, each self-contained; shared consumer-sweep notes are
129	repeated in every affected file.
130	- Whole-project mode writes the per-component files plus
131	`.migration/project.md` (dependency swap, app-code sweep summary, final
132	build result).
133	- There is NO index file. Migration status is derived from disk, not
134	maintained: scan the project's ui directory (the `ui` alias from shadcn
135	info, e.g. components/ui or src/components/ui) for remaining radix imports
136	when asked "what's left". End every run's summary with that derived count
137	("N wrappers remain on Radix").
138
139	Each `.migration/<component>.md` uses EXACTLY this structure (it is
140	documented publicly; reports must match it):
141
142	```md
143	# <component>
144
145	<date, strategy used (golden pair via CLI / merge / engine), one-line verdict>
146
147	## Changed
148
149	<every file touched, with what changed and why; include file:line for
150	anything notable. Confirm the leftover scan is clean:
151	grep -n "radix-ui\\|@radix-ui" on this component's files>
152
153	## Left alone
154
155	<files that look related but were intentionally not touched, with the reason
156	(cmdk/vaul/sonner are not radix; unrelated drift; etc.)>
157
158	## Behavior changes
159
160	<differences that compile fine but act differently; flagged, never patched
161	(tabs activation, menu close-on-click, delays...). Empty section if none>
162
163	## Verify by hand
164
165	<short manual QA checklist for this primitive family: focus return on
166	dialogs, keyboard nav + typeahead on menus/select, tooltip delay feel,
167	slider commit events. Concrete steps, one minute of clicking>
168	```

6 picks

Type

Run `npx skills use "https://github.com/shadcn/ui" --skill "shadcn/ui/migrate-radix-to-base"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/shadcn/ui" that are relevant to the current task. Run `npx skills add "https://github.com/shadcn/ui"` and select the relevant skills, then follow their instructions.

migrate-radix-to-base

How to install migrate-radix-to-base?

Related

migrate-radix-to-base

How to install migrate-radix-to-base?

Related