NextUI to HeroUI: run the rename and package gate before product work

HeroUI is the same designed React component system NextUI already was — under a new package identity, with an official codemod that rewrites @nextui-org/* → @heroui/*, Tailwind plugin wiring, and the provider import in one pass. For teams that already standardized on NextUI, that rename is real use: you keep the API surface you trained on and stop shipping a retired org name into every lockfile and agent prompt.

The part that still burns weeks is treating the rename as “done” the moment the codemod exits zero. Product work should wait until the package gate, Tailwind content paths, and (if you are also moving to HeroUI v3) the React 19 + Tailwind CSS v4 install surface are verified. This post is that gate — not a suite-vs-headless debate, and not an owned-kit twin.

Cast scene: package, config, and provider checklist before product work continues.

What the NextUI → HeroUI rename actually changes

HeroUI’s NextUI to HeroUI migration guide is explicit: HeroUI is the new identity for NextUI, and the recommended path is the official @heroui/codemod migrate command. In a monorepo, run it from the root. The documented automatic steps:

• Rewrite package names from @nextui-org/* to @heroui/*
• Rename component imports and references
• Update Tailwind CSS configuration (plugin + theme content globs)
• Transform provider components (NextUIProvider → HeroUIProvider)
• Adjust NextUI-specific utilities or hooks
• Update .npmrc hoist patterns for pnpm only

The guide’s verification claim matters for planning: functionality and API stay the same for this rename — package names and imports change. That is why this is a gate, not a redesign.

Source: v2.heroui.com/docs/guide/nextui-to-heroui, captured 2026-09-17.

How do I run the rename codemod today?

From the app (or monorepo root) that still depends on @nextui-org/react:

# npm
npx @heroui/codemod@latest migrate

# pnpm
pnpm dlx @heroui/codemod@latest migrate

# yarn
yarn dlx @heroui/codemod@latest migrate

# bun
bunx --bun @heroui/codemod@latest migrate

Then install so the new @heroui/* packages land in the lockfile:

npm install
# or: pnpm install / yarn install / bun install

Manual equivalent if you skip the codemod (same guide): uninstall @nextui-org/react, install @heroui/react, swap the Tailwind plugin from nextui to heroui, point content at @heroui/theme, and replace provider/imports.

// Before
const { nextui } = require("@nextui-org/react");
module.exports = {
  content: ["./node_modules/@nextui-org/theme/dist/**/*.{js,ts,jsx,tsx}"],
  plugins: [nextui()],
};

// After
const { heroui } = require("@heroui/react");
module.exports = {
  content: ["./node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}"],
  plugins: [heroui()],
};

// Before
import { NextUIProvider, Button } from "@nextui-org/react";

// After
import { HeroUIProvider, Button } from "@heroui/react";

pnpm-only .npmrc swap from the same guide:

# Before
public-hoist-pattern[]=*@nextui-org/*

# After
public-hoist-pattern[]=*@heroui/*

Verify checklist before you resume product work

Run these before the next feature PR, not after design review complains.

1. Lockfile hygiene. package.json / lockfile contain zero @nextui-org/* deps (codemod troubleshooting calls this out explicitly).
2. Import grep. No remaining @nextui-org/ or NextUIProvider in app and package source.
3. Tailwind content. Theme dist glob points at @heroui/theme, plugin is heroui(), not a half-migrated mix.
4. Provider root. One HeroUIProvider wraps the tree your screens actually render.
5. Build + smoke. Production build clean; light/dark and a few high-traffic composites (Button, Input, Modal/Dropdown) still match your theme tokens.
6. npm recovery. If install is weird after the swap, the guide’s npm path is delete node_modules + package-lock.json, then npm install.

# Fail the gate if any of these still resolve
rg -n "@nextui-org/|NextUIProvider|from ['\"]@nextui-org" apps packages src || true
rg -n "plugins:\\s*\\[.*nextui|@nextui-org/theme" --glob 'tailwind.config.*' || true

If any line still hits, stop product work. Agents will happily invent “fixed” imports that reintroduce the old org name.

Cast scene: verified stamp after the checklist clears.

HeroUI v3 quick-start is a different surface — do not invent it from the rename

The rename guide above is the NextUI → HeroUI (v2-line) identity migration. Separately, HeroUI’s current React quick start documents a v3 install surface with different requirements:

• React 19+
• Tailwind CSS v4
• npm i @heroui/styles @heroui/react
• CSS import order: @import "tailwindcss"; then @import "@heroui/styles"; (Tailwind first)

npm i @heroui/styles @heroui/react

@import "tailwindcss";
@import "@heroui/styles";

import { Button } from "@heroui/react";

export function App() {
  return <Button>My Button</Button>;
}

Treat that as a second gate if your roadmap includes v3 — not as something the rename codemod silently finished. At draft time, a dedicated “full v2→v3 migration” how-to URL on heroui.com/docs/guide/... did not return usable migration steps via fetch (404 on the paths checked); only cite the verified rename guide plus the verified v3 quick-start until HeroUI publishes an explicit full-migration page you can link.

HeroUI’s own intro positioning (Tailwind CSS + React Aria, npm components rather than copy-paste-only) is useful context for why the package rename is worth doing carefully — you are preserving a designed, accessible React system, not swapping CSS class lists. See the HeroUI introduction for that framing.

How this gate differs from suite depth and primitives decisions

If your open question is “how many specialty packages do we standardize on for web SaaS?”, that is the suite-vs-assembly worksheet in Mantine full suite vs a thinner headless stack. If the question is “do we own a designed catalog or stay on unstyled primitives?”, use Radix primitives vs a designed kit. Stay-or-leave for another web-first library lives in posts like Chakra UI’s web-only decision.

This post is narrower: you already picked the NextUI/HeroUI designed system — now finish the rename and package verification before the next feature sprint.

When an owned product spine is the complementary move

Finish the HeroUI gate first when the UI library is not the bottleneck. When the bottleneck is screens, auth, payments, and agent-readable product context sitting in one owned repo, browse the OTF templates catalog — free MIT SDK (@otfdashkit/ui and related packages) plus paid full-stack kits ($99 / bundle $149) with live demos such as saas.otf-kit.dev. That is complementary to HeroUI, not a reason to skip the codemod.

Agent prompts and CI should treat @nextui-org as a failing check

Once humans migrate, coding agents still paste yesterday's imports. Put the gate in the same place agents read:

• Cursor / Claude project rules: "never import @nextui-org/*; use @heroui/* and HeroUIProvider."
• CI: a cheap rg job that fails the PR if @nextui-org appears under apps/ or packages/ (exclude node_modules and historical changelogs).
• PR template: link this checklist so reviewers do not argue from memory.

That is the difference between a one-hour rename and a month of half-migrated PRs. The library did its job; the repo hygiene is yours.

Practical recommendation

1. Appraise the rename: official codemod, same component API, clearer package identity.
2. Run npx @heroui/codemod@latest migrate (or package-manager equivalent) from the monorepo root, then install.
3. Clear the verify checklist (imports, Tailwind globs, provider, build smoke) before product PRs.
4. If adopting HeroUI v3, run the React 19 + Tailwind v4 + @heroui/styles install as its own gated change — do not assume the rename covered it.
5. Keep suite-depth and primitives debates in their own decision posts; do not collapse them into this how-to.

Ship the rename cleanly, prove the packages, then resume features on the library you actually intended to keep.

Sources

• NextUI to HeroUI migration guide (codemod, Tailwind, provider)
• HeroUI React quick start (v3: React 19+, Tailwind CSS v4, @heroui/styles)
• HeroUI introduction (Tailwind CSS + React Aria positioning)
• OTF templates