Fixing Radix UI Dependency Conflicts in Shadcn (2025 Guide)

You just added a new Dialog component from Shadcn, and suddenly your whole project is a sea of red. Your npm install is failing with "ERESOLVE: could not resolve dependency node_modules," and your IDE is throwing a cryptic error: "Type 'ReactNode' is not assignable to type 'JSX.Element'."

Welcome to "Radix Version Hell."

Shadcn UI is not a traditional npm package. It is a collection of source code that you copy into your project. However, that source code depends on Radix UI Primitives—tiny, specialized packages for each UI element (like @radix-ui/react-dialog or @radix-ui/react-dropdown-menu).

Because Shadcn components are updated independently, you might end up with one component that wants Radix v1.0.0 and another that wants v1.1.0. For "Vibe Coders" using AI to manage their packages, this is an invisible barrier. The AI suggests "reinstalling the package," but that often makes the conflict even worse.

In this guide, we’ll show you how to identify Radix version mismatches, how to use overrides to force your project into compliance, and the "nuclear option" for cleaning up your dependency tree.

How Shadcn Uses Radix UI Primitives

To fix the engine, you have to understand how it’s built.

Shadcn components (like Button, Dialog, and Select) are built on top of Radix. Radix provides the "behavior" (accessibility, keyboard navigation, state), and Shadcn provides the "styling" (Tailwind CSS).

When you run npx shadcn-ui@latest add dialog, the CLI does two things:

1. It copies the .tsx file into your /components/ui folder.
2. It runs npm install @radix-ui/react-dialog.

If you already had a different version of a Radix package installed—perhaps from an earlier Shadcn installation or a manual install—npm may struggle to resolve which version should "win."

Identifying Version Conflicts in Your package-lock.json

If your build is failing, the first place to look isn't your code; it's your lockfile.

The "npm list" Diagnostic

Run this command in your terminal to see every Radix package currently installed: npm list --depth=2 | grep radix

If you see multiple versions of the same package (e.g., @radix-ui/react-slot@1.0.1 and @radix-ui/react-slot@1.1.0), you have a conflict. These "duplicate" packages lead to the dreaded "Component cannot be used as a JSX component" error.

Common Error: 'Component cannot be used as a JSX component'

This error is the #1 symptom of Radix version hell. It happens because TypeScript sees two different definitions of the same Radix primitive. It thinks they are incompatible, even if they are only one patch version apart.

If your Button.tsx is throwing this error on the <Slot> component, it’s almost certainly because of a version mismatch between @radix-ui/react-slot and the rest of your UI stack.

The Fix: Using 'npm overrides' or 'pnpm.overrides'

The most robust way to fix this is to tell npm: "I don't care what the component wants; use THIS version for everything."

1. Identify the latest version

Go to the Radix UI Documentation or check npmjs.com to find the current latest versions of the primitives.

2. Update your package.json

Add an overrides field (for npm) or resolutions (for yarn) to force all instances of a package to a single version.

{
  "name": "my-app",
  "version": "0.1.0",
  "dependencies": { ... },
  "overrides": {
    "@radix-ui/react-slot": "1.1.0",
    "@radix-ui/react-primitive": "2.0.0"
  }
}

Note: For pnpm users, use the pnpm.overrides field instead.

Clean Reinstallation: The Nuclear Option

If overrides doesn't work, your node_modules might be corrupted with "phantom" packages. It’s time for a clean slate.

The Workflow:

1. Delete the lockfile: rm package-lock.json
2. Delete node_modules: rm -rf node_modules
3. Clean the cache: npm cache clean --force
4. Reinstall: npm install

This forces npm to recalculate the entire dependency tree from scratch. If you have the overrides field in your package.json, this fresh install will respect those versions globally.

Preventing Conflicts when Adding New Shadcn Components

To avoid hitting this wall every time you add a UI element, follow these best practices:

1. Always use @latest: Run npx shadcn-ui@latest add, not just shadcn-ui add. This ensures you are getting the most modern component source code.
2. Commit your lockfile: Before adding a new component, ensure your git working directory is clean. If the installation breaks your project, you can git checkout . to revert the changes.
3. Audit your peer dependencies: When you see a "Peer Dependency Warning" during npm install, don't ignore it. It is the AI's way of telling you that "Radix Version Hell" is imminent.

FlowQL: Human Expertise for Complex UI Engine Failures

Dependency management is one of the "last 20%" tasks that AI is remarkably bad at. AI models don't have access to your live node_modules tree, and they can't "feel" the friction of a broken lockfile. They will suggest infinite loops of npm install that never solve the underlying version conflict.

At FlowQL, we specialize in these deep technical roadblocks. When your Shadcn installation is paralyzed by peer dependency errors and your "Vibe" is officially broken, we provide the senior technical oversight to manually untangle your dependency tree and get your UI engine running again.

Conclusion

Radix dependency conflicts are a natural byproduct of Shadcn's "copy-paste" architecture. By understanding the link between the source code and the primitives, using overrides to enforce version consistency, and knowing when to use the "nuclear" clean install, you can resolve these errors in minutes.

Don't let a lockfile conflict stop your design momentum. [Book a session with FlowQL] and let's get your Shadcn UI perfectly configured.

---

FAQ: Shadcn and Radix Dependency Issues

Q: Do I need to manually install Radix UI? A: No. The Shadcn CLI will automatically install the necessary Radix primitives for you. You only need to intervene if there is a version conflict.

Q: What is the difference between @radix-ui/react-slot and other primitives? A: @radix-ui/react-slot is a foundational package used by almost every Shadcn component to support the asChild prop. Because so many things depend on it, it is the most frequent source of version conflicts.

Q: Can I use Shadcn with Yarn or pnpm? A: Yes. Shadcn works with all major package managers. Just ensure you use the correct field for version overrides (resolutions for Yarn, pnpm.overrides for pnpm).