HeroUIをNext.js×Tailwind CSS v4に導入する方法について

個人開発で、Next.jsとTailwind CSS v4のプロジェクトにHeroUIを導入しようとしました。

しかし、Tailwind CSS v4のキャッチアップをあまりできていなかったことと、pnpmでインストールをしたことによって、導入に時間を要してしまいました。

同じような方（と自分）がスピーディに環境構築ができるように、HeroUIの導入方法をまとめておこうと思います。

HeroUIとは？

Webサイトやアプリケーション開発において、魅力的なUIの構築は不可欠です。そこで注目を集めているのが、モダンなWeb開発を強力にサポートするフレームワーク「HeroUI」です。

HeroUIは、コンポーネントベースのアプローチを採用しており、再利用性の高い部品群を提供します。これにより、開発者はゼロからUI要素を構築する手間を省き、一貫性のあるデザインを効率的に実現できます。また、レスポンシブデザインにも対応しているため、デスクトップからモバイルデバイスまで、あらゆる画面サイズに最適化された表示が可能です。

直感的で分かりやすいAPIと充実したドキュメントにより、学習コストが低い点も大きな魅力です。Python、JavaScript、TypeScriptなど、幅広い技術スタックを持つソフトウェアエンジニアにとって、HeroUIは開発プロセスを加速し、高品質なプロダクトを生み出すための強力な味方となります。

この記事の環境

念の為、筆者がHeroUIを導入したときの環境やバージョンを示しておきます。

導入方法について

それでは、実際にHeroUIを導入していきましょう。

こちらの公式サイトをもとに導入していきます。途中、Viteを利用している人のみ注意する点があるため気をつけてください。（詳細は公式サイト）

1. HeroUI（ベータ版）をインストールする

npmの場合
npm install @heroui/react@beta

pnpmの場合
pnpm install @heroui/react@beta

2. CSSの編集

Tailwind v4の大きな変更点として、tailwind.config.jsが不要であることです。

そのため、今までHeroUIを導入するときにtailwind.config.jsに書いていたコードが不要になります。その代わりに、hero.tsを作成します。

// hero.tsに以下をコピー
import { heroui } from "@heroui/react";
export default heroui();

次に、global.cssを編集します。

@import "tailwindcss";
@plugin './hero.ts';
// 以下のパスは適宜変更
@source '../../node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}';
@custom-variant dark (&:is(.dark *));

注意点としては、v3までのときに記述していた、tailwind.config.jsの内容ではないことです。

// 以下3行は不要
@tailwind base;
@tailwind components;
@tailwind utilities;

一応、tailwind.config.jsにも対応しており、その場合は記述方法が少し変わるそうです。ここでは、最新バージョンに合わせて話を進めます。

3. postcss.config.jsを編集

次に、postcss.config.jsを以下のように編集します。

// postcss.config.js
- export default {
-   plugins: {
-     tailwindcss: {},
-     autoprefixer: {},
-   },
- };

+ export default {
+   plugins: {
+     "@tailwindcss/postcss": {},
+   },
+ };

以上で、HeroUIを導入できたはずです。問題なくビルドができ、UIライブラリが使えることを確認しましょう。

まとめ

今回は、Next.js x Tailwind CSS v4プロジェクトにHeroUIを導入する方法について解説しました。

Tailwind v3のときは、pnpmでインストールすると.npmrc関連に気を付ける必要がありましたが、v4でその必要がなくなりました。

しかし、まだベータ版らしいのでアップデートに注意する必要があるかもです。