Tailwindcss v4バージョンアップへの道のりをCursorと共に駆け抜けた話
はじめに
はじめまして!イノベーション開発チームのchisato🎮です!
弊社が運営するITトレンドのスタイルの実装にTailwindcssを採用しています。今年のはじめにはv4という大きな変更が入ったバージョンがリリースされ、MCPサーバーやら開発組織としてのガイドラインの統一をしたりという話になり、スタイル周りも整えていきたいということで重い腰を上げてバージョンアップに取り組むこととなりました。
そんな重い腰を上げる手助けになってくれたのがCursorだったので、どんな手順でバージョンアップをしたのか、Cursorをどんな風に活用したのかをお話しできればと思います。
前提
対象読者
- Tailwindcssのバージョンアップを行いたいがなかなか踏み出せずにいる方
- Cursorの導入を検討している方
バージョンアップ前環境
- NextJS: 15.2.4
- Tailwindcss: 3.4.7
- Sass: 1.83.4
※開発方針の変更によってTailwindcssとSassが混在
Tailwindcssとは
クラス名だけでUIを組み立てる、ユーティリティファーストのCSSフレームワークです。
最近はv0等でもtailwindcssを使って出力されることもあってAIとの親和性を考えて導入する企業さんも少なくないようですね。
v3からv4で何が変わった?
v3からv4にアップグレードするにあたっていくつか破壊的な変更が含まれていますので簡単にご紹介します。
詳細はこちら→https://tailwindcss.com/docs/upgrade-guide#changes-from-v3
1. ユーティリティが"数字直書き"で通るようになった
例:w-640
、z-1000
、grid-cols-15
がそのまま JIT で解釈され、角括弧 []
や theme.extend
が不要になりました。
container
/ring
など基幹クラスの既定値を再定義
2. - containerのmax-widthが
ブレークポイント値そのまま
となり、左右のpaddingも0になったので-2px問題がなくなりました。 -
ring
/shadow
/rounded
/blur
のデフォルト値が変更になりました。
hover:
, sm:
, dark:
…)の CSS 出力順が変わり優先度が逆転
3. バリアント(右→左だった v3 の並びが v4 では 左→右(CSS 本来の後勝ち順) に統一されました。
同じセレクタ特性のクラスでも、記述順で見た目が変わる可能性があります。
tailwind.config.js
から "CSS に直接書く" 方式へシフト
4. カスタム設定が v4 からは @theme
, @utilities
, @components
などのディレクティブを CSS 内で使い、カラー・間隔・フォントスケールをそのままエディタ上で上書きできる 仕組みが追加されました。これにより「設定ファイルを開く → コンパイルを待つ」という往復が不要になり、デザイントークンの微調整がリアルタイムに反映されるようになりました。
アップグレードツールもあったにも関わらず苦戦
tailwindcssではアップグレードツールが用意されていたので、作業は一瞬簡単に思えましたが、実際は手作業で対応しなければいけない箇所が大量に発生しました。手作業が必要になったポイントは以下の2つでした。
- Gitがインストールされていないdockerコンテナ上でアップグレードを使用したが、このアップグレードツールはGitを使用することが前提であったこと
- NextJSにリプレイスした当初SASSを使用する方針を途中からtailwindcssに変更していったことにより、SASSとtailwindcssが混在していたこと(v4ではSASS等のCSSプリプロフェッサと併用するような設計にはなっておらず、併用しないようにと記載がある)
大量の手作業を助けてくれたのがCursorくん
SASSファイルがなんと200ファイル近く存在していたのでそれを全てCSSに置き換えるのは流石に手作業では骨が折れると思いました。最初はDevinに作業をお願いして実行しようとしたが、あまりの作業量の多さにACUの枯渇問題にぶち当たり、彼にはまだまだ荷が重かったようです、、、
そんな時に代わりに登場したのがCursorくんの登場です!
上の記事でも紹介があったように、まずはCursorくんにお願いするためのプロンプトをChatGPTにお願いして作成してもらい、それをCursorくんに投げて作業をしてもらいました。
Cursorに投げたプロンプト例(あくまでも例です)
🖱️ Cursor プロンプト — Tailwind CSS v3 → v4 & SCSS→CSS 移行(モジュール別 :global 分離)
必ず参照: • Tailwind 公式アップグレードガイド https://tailwindcss.com/docs/upgrade-guide
🎯 ゴール
- Tailwind CSS を v4 へアップグレード。
- 各 *.module.scss の :global { ... } ブロックを 同階層の global_<basename>.css に抽出。
- それ以外の SCSS を .css へ拡張子変更した上で @apply を維持。
- container など Breaking Changes をすべて解消し、npm run build・Storybook・Vitest・CI を GREEN にする。
🗒️ Cursor への指示(そのまま貼り付けて実行)
以下のステップを順番に実行してください。各ステップが完了したら ✅ Done <STEP>
とコメントを残し、次のステップへ進んでください。
STEP 1 — 公式アップグレードスクリプトの実行
ターミナルで:
npx @tailwindcss/upgrade@next --yes
完了後、git status を確認して変更をコミット。
STEP 2 — :global 抽出スクリプトの生成
scripts/extract-global-per-module.js を新規作成し、以下のロジックを実装:
// 1. *.module.scss を再帰走査
// 2. :global { ... } を抜き出し
// 3. ネスト解除 & 変数展開 (postcss)
// 4. 同フォルダに global_<basename>.css を生成
// 5. 元ファイルから :global ブロックを削除
依存: npm i -D postcss postcss-nested glob fast-glob
STEP 3 — SCSS → CSS 変換
- Cursor の Multi-File Rename で *.module.scss → *.module.css。
- scripts/convert-scss.js を作り、postcss-nested でネストを平坦化。
- ターミナルで実行し、変更をコミット。
STEP 4 — Breaking Changes 修正
- Multi-file Search で space-x- / divide-x- などを検索し、公式ガイドの置換ルールで修正。
- container に mx-auto を追加。
- checked:bg-* → peer-checked:bg-* 等、state+color を修正。
STEP 5 — 設定ファイル更新
- tailwind.config.ts を ESM 形式に。content 配列を pages/components/src に拡張。
- postcss.config.mjs に postcss-nested を追加。
- Storybook の preview.ts で共通 global CSS を import。
STEP 6 — Lint / Test / Build
npm run lint:fix && npm run lint:style:fix && npm run test && npm run build
ビルドが通るまで上記ステップを微調整。
STEP 7 — 変更した内容のまとめ回答
- 変更をコミット: feat: Tailwind v4 & module-scoped global CSS。
- 以下を回答:
- 参考リンク: https://tailwindcss.com/docs/upgrade-guide
- 完了チェックリスト(ビルド・Storybook・Vitest・CI GREEN)
- どのような変更を行なったかとその内容
- 破壊的な変更を行なったかとその内容
- 他に参考にした文献はあるかどうか
👆 この指示の各サブステップが終わるごとに、Cursor のチャットに ✅ Done を投稿して進めてください。
Cursorを活用して良かった点
修正の方向性を確認しながら進めることができたこと
Devinくんのように勝手にどんどん作業を進めて動いてくれることも魅力的ではあります。しかし、今回に関してはこちらが意図した修正をして欲しかったポイントが多かったため、まず1,2ファイルほど修正してもらい、その修正内容を確認した上で他のファイルに対しても実行してもらえたので、修正数に対して方針の齟齬が大きくは生じずに変更を行うことができました。
手作業に対しても今までの作業から補完が効くこと
Agentモードで修正を実行していましたが、ファイル数が多かったことから多少修正されないファイルも実際には存在しました。そのファイルに関しては多少手作業が発生しましたが、今までの修正を基に入力補完が効いていたのでほとんど作業をせずに修正を完了させることができました。
まとめ
結果、バージョンアップに際して変更したファイル数は約600ファイルに及びましたが、Cursorくんの活躍によって作業時間は半日以下で済みました。(テストは別途時間はかかっていますが、、、)
このファイル数を手作業でやっていたら、、、と思うと恐ろしいですね、、、Cursor様様。
とはいえ、たくさんのAIツールが台頭している中で、そのAIツールの特徴を踏まえて使い分けられると、より効率的に開発を進めることが行えることがよく分かり、Cursorは割と並走して作業を進めたい場合に有効だと感じました。
あとは、今回はSASSとtailwindcssを併用していたことによる作業量の増大も大きな要因ではあったので、様々なツールの併用にはリスクが伴うということを身をもって実感しました、、、
最後まで読んでいただきありがとうございました!
少しでも参考になれば幸いです!
Discussion