Building with shadcn/ui?

shadcn/ui CLI broken or theme drifting? We bring it back.

shadcn/ui is beautiful until the CLI refuses to add a new component because components.json points at a path that no longer exists, your Tailwind v4 upgrade reshapes the tokens, or a Radix popover crashes during Next.js hydration because the trigger ref was null on the server. We trace the path aliases, the CSS variables and the client-component boundaries until the shadcn copy-paste model actually behaves as advertised.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

shadcn-cli.log

still failing

What it is

shadcn/ui at a glance

shadcn/ui is a collection of accessible React components by Shad (shadcn) that you install into your own codebase rather than pull in as a dependency. The CLI copies the source of each component, built on Radix UI primitives and styled with Tailwind, directly into your repository. Because the code lives with you, there is no version to upgrade and no third-party package to pin.

The approach has reshaped how modern Next.js, Remix and Astro teams think about UI libraries: you own the code, you style it with Tailwind CSS variables and a theme file, and you register and update components through a small CLI that reads a components.json manifest at the project root. Problems tend to cluster around the CLI (path aliases pointing at the wrong folder, Tailwind config drifting between versions, missing peer dependencies like tailwindcss-animate, cmdk or @radix-ui/react-popover), SSR hydration (Radix primitives that mount their portals on the client only, client components flagged incorrectly), and theme token drift once teams fork components without a plan.

Type
Copy-paste React component collection built on Radix UI and Tailwind CSS
First released
2023
License
MIT, open source, free
Maintained by
shadcn (Shad) and community contributors
Typically used for
Next.js and Remix front ends, dashboards, SaaS apps and marketing sites that need a custom look without a UI library dependency

The honest version

shadcn/ui pros and cons

No technology is all upside. This is where shadcn/ui earns its place and where it tends to cause trouble.

Where shadcn/ui is strong

  • You own the component codeEach component is copied into your repo, so there is no third-party version to chase and no breaking change that arrives uninvited through npm install.
  • Radix primitives do the hard workKeyboard handling, focus trapping, ARIA roles and portal logic come from Radix UI, which is widely used and well tested, so the components are accessible out of the box.
  • Tailwind-native stylingClasses and CSS variables sit in the component source, so changing a radius, a color or a focus ring is a one-line edit in a file you already know.
  • The CLI is small and predictable`npx shadcn add button` reads components.json, pulls the current source from the registry, writes it to your path alias, and leaves you in charge. No hidden runtime.
  • Great starting point for design systemsTeams fork the registry, point the CLI at their own registry URL, and ship an internal design system with the same workflow their engineers already use for the public one.
  • Big, friendly ecosystemTemplates, blocks, charts, dashboards and third-party registries (Aceternity, Origin UI, Tremor) all follow the same copy-paste pattern, so composing from them is straightforward.

Where shadcn/ui bites

  • You inherit every componentOnce you copy a component, bug fixes and improvements from upstream do not come down automatically. Keeping up with the registry needs a review process you have to build yourself.
  • Tailwind config and CSS variables drift fastDifferent components assume slightly different token names across releases, and a Tailwind v3 to v4 jump reshapes the config entirely. Theme files silently fall out of alignment with the components installed before the upgrade.
  • Peer dependencies are easy to misstailwindcss-animate, cmdk, date-fns, react-hook-form and various @radix-ui/* packages are assumed. Missing one does not surface until the component is rendered the first time.
  • SSR requires the client-component boundary to be correctRadix primitives need to run in client components, and a server component that imports a Dialog or Popover will hydrate oddly or crash. The pattern is simple once you see it, but the error messages are not.
  • No single source of truth for the component surfaceEach repository ends up with a slightly different Button after a few months, and without a design-system discipline the drift turns into real design inconsistency.
  • Still a one-maintainer projectThe pace is fast, but the registry and the CLI live and die with a small core team. Teams that need enterprise commitments usually fork their own registry rather than rely on upstream.

Sound familiar?

Common shadcn/ui problems we fix

The shadcn/ui problems that bring people to us, and what you have once each one is fixed.

No components.json file found

The CLI will not add a component to a fresh project

An init that was skipped, a components.json that lives in a monorepo workspace the CLI does not detect, or a tsconfig path alias that no longer points at the ui folder after a refactor.

CLI aware of your project layout

style `default` not supported with Tailwind v4

A Tailwind v4 upgrade breaks shadcn styles

Tailwind v4 moved to a CSS-first configuration and reshaped the plugin system, which means tailwind.config.js tokens no longer feed shadcn components the way they did. We rebuild the theme in the new @theme block and reintroduce the CSS variables the components expect.

Theme aligned with Tailwind v4

Hydration failed because the server HTML did not match

Radix Dialog or Popover crashes on hydration

A shadcn component imported into a server component without the `use client` directive, or a controlled Dialog whose default state differs between server and client renders.

Client boundary correct, hydration clean

Could not resolve `tailwindcss-animate`

A peer dependency is missing

A component that assumes tailwindcss-animate, cmdk or an @radix-ui/* subpackage, installed in an environment where the dependency was never added. Build fails only when that component ships to production.

Peers installed and pinned

window is not defined (lib/utils.ts)

lib/utils.ts breaks server rendering

A utility that reaches for `window` or `document` at module scope, usually added by a developer who did not expect the file to be imported into a server component. The whole route fails to render.

Utilities safe on server and client

CSS variable --primary not defined in :root

Component colors fall back to initial

A globals.css that was overwritten during an upgrade, or a theme file that defines variables for one style (default) but not the other (new-york). The button loses its background entirely.

Theme variables restored across styles

component `dropdown-menu` already installed

CLI refuses to update a component

Local edits that would be lost on overwrite, or a CLI that is not sure which file is the newer one. We diff the local copy against the current registry and merge deliberately rather than blindly overwriting.

Components updated, local changes preserved

cmdk: cannot find module

Command palette does not build

The Command component depends on cmdk, which is not always installed by default. The build passes until the palette is first mounted, and then the page crashes on render.

Palette installed, modules resolved

What we do

shadcn/ui help, from CLI to design system

Call us for one broken component, or let us own the whole shadcn registry and design system.

Rescue
A CLI that will not add components, a Tailwind v4 upgrade that stripped the theme, or a Radix primitive crashing in production. We stabilise first and explain second.
Theme and token design
CSS variables, dark mode, radius, typography and semantic tokens expressed once and consumed by every component, with a plan for keeping them stable across upgrades.
Private registries
A forked registry served from your own URL so internal components ship through the same shadcn CLI the team already uses. Versioning, authentication and auditing included.
SSR integration
Next.js App Router, Remix and Astro setups wired so Radix primitives render cleanly on hydration, with the client-component boundaries drawn in the right places.
Upgrades and audits
Component drift reviewed against the current registry, local customisations documented, and breaking upstream changes applied with codemods where possible.
Managed Tech
Weekly registry checks, Tailwind and Radix dependency rotation, performance budgets on the component surface, and a React engineer on call when the next major release lands.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running shadcn/ui alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

shadcn/ui questions

Something else? Call+1 737 727 7327

Why does the shadcn CLI say my components.json is missing?

Usually one of three reasons: the init step was skipped on the project, the CLI is being run from a monorepo root that does not contain components.json while the workspace that does lives deeper, or the file exists but references a path alias (@/components/ui) that no longer resolves against the current tsconfig. We re-run init pointing at the right workspace and verify the path alias before anything else.

How do we upgrade shadcn components without losing our local changes?

By treating the component files like forked code and merging upstream changes deliberately. We fetch the current source from the registry, diff it against the local copy, apply fixes and improvements piece by piece, and keep notes on what diverges intentionally. Blind overwrites are what cause teams to lose a week of design tweaks.

How should we migrate shadcn/ui to Tailwind v4?

Tailwind v4 moves configuration into CSS through the @theme block, so the tailwind.config.js approach that shadcn assumed by default no longer works. The correct path is to generate a v4-compatible components.json style, migrate the theme tokens into @theme, and reinstall any components that use utilities Tailwind v4 renamed. We rehearse the move on a branch before pushing it to main.

Why does our shadcn Dialog crash during hydration?

Radix primitives need to live in client components, and any file that imports Dialog, Popover, DropdownMenu or Select must start with the `use client` directive in Next.js App Router. Hydration errors also come from controlled components whose default state differs between the server and the first client render. The fix is to put state on the client side only or seed the server render from the same source.

Can we host a private shadcn registry for our internal design system?

Yes, and this is becoming a common pattern. A registry is a set of JSON files served over HTTPS, each describing a component and its source. We set up a private registry (on Cloudflare R2, S3 or a Next.js route), add authentication, and point the CLI at it through the registry URL in components.json. Internal components then install through the same workflow as the public ones.

How much does shadcn/ui help cost?

The estimate is free. Send over the components.json, the Tailwind config and a short note on what is broken, and we come back with a scope and a price before anyone commits code.

Free estimate

shadcn/ui giving you trouble?

CLI setup, Tailwind v4 migrations, SSR hydration, private registries and design-system discipline across shadcn forks. We work on both the component source and the wider React layer.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.