🐱

Next.js & HeroUI(NextUI)環境のTailwindをv3→v4にアップグレードする

2025/07/22に公開

HeroUI(NextUI)がようやくv2.8系でTailwind v4に対応されたので、
Next.js & HeroUI(NextUI)の構成で利用している環境のTailwindをv3からv4にアップグレードしてみます。

基本的には下記HeroUIのTailwind v4アップグレード手順を参考にします。

Tailwind自体のv3→v4へのアップグレード

まずはTailwind公式のv4アップグレード手順でTailwind自体をアップグレードします。
基本的にはコマンド一発なのですが、前準備としてHeroUIのプラグインを外しておきます。
※プラグインを外しているのは、入れたままだとアップグレードコマンドでエラーになった為です。

HeroUIのプラグインを外す

tailwind.config.ts(js)

plugins: [heroui()],

↓

tailwind.config.ts(js)

plugins: [],

ちなみに、tailwind.config.tsはアップグレード時に削除されます。
設定している他の内容は、globals.cssに自動的に移植されます。

Tailwind v4アップグレードコマンド

基本的に下記公式の手順を参考にします。

Tailwindのアップグレードは専用コマンドで実施します。

$ npx @tailwindcss/upgrade

Git管理で未コミットの内容があると実行できないので、その場合は--forceのオプション付けて
実行します。

$ npx @tailwindcss/upgrade --force
≈ tailwindcss v4.1.11

│ Searching for CSS files in the current directory and its subdirectories…

│ ↳ Linked `./tailwind.config.ts` to `./src/styles/globals.css`

│ Migrating JavaScript configuration files…

│ ↳ Migrated configuration file: `./tailwind.config.ts`

│ Migrating stylesheets…

│ ↳ Migrated stylesheet: `./src/styles/globals.css`

│ Updating dependencies…

│ ↳ Updated package: `tailwindcss`

│ ↳ Updated package: `prettier-plugin-tailwindcss`

│ Migrating templates…

│ ↳ Migrated templates for configuration file: `./tailwind.config.ts`

│ Migrating PostCSS configuration…

│ ↳ Installed package: `@tailwindcss/postcss`

│ ↳ Migrated PostCSS configuration: `./postcss.config.mjs`

│ Verify the changes and commit them to your repository.

こんな感じで自動で移行してくれます。
※環境によっては手動フォローが必要かもしれません。

HeroUIをv2.8系にアップグレード

Tailwind v4を利用するにはHeroUIをv2.8系にアップグレードする必要があるので、アップグレードします。

$ yarn upgrade-interactive
 Press <up>/<down> to select packages.            Press <enter> to install.
 Press <left>/<right> to select versions.         Press <ctrl+c> to abort.

? Pick the packages you want to upgrade.          Current          Range            Latest

 > @heroui/react ------------------------------- ◯ 2.7.11 ------- ◉ 2.8.1 --------

自分はyarnのupgrade-interactiveコマンドで最新バージョンに入れ替え。
自環境で利用のコマンドで@heroui/reactパッケージを最新化してください。

HeroUIをTailwind v4に再組み込み

HeroUIのプラグインを外していますので、v4用に組み込みなおします。

globals.cssの同ディレクトリにhero.tsファイルを作成し、下記のように記述します。

hero.ts

import { heroui } from '@heroui/react'
export default heroui()

そして、globals.cssにプラグインの記述を追加します。

globals.css

@import 'tailwindcss';
@plugin './hero.ts';

これで完了です！
自分の環境では特に問題なく動きました。