hrdtbs' blog
Search contents

AstroでTailwind CSSをv4にアップグレードした

Tailwind CSS v4 について#

2025 年 1 月に Tailwind CSS v4 がリリースされた。

https://tailwindcss.com/blog/tailwindcss-v4

Tailwind CSS v4 では、新機能に加えてユーティリティの変更や削除、設定方法の変更などを含んでいるため、移行作業が必要になる。

アップグレードツールを試す#

まずは、公式のアップグレードガイドにも記載されている自動アップグレードツールを実行してみた。

https://tailwindcss.com/docs/upgrade-guide

Terminal window
npx @tailwindcss/upgrade@next

@tailwindディレクティブの削除や、名前が変更されたユーティリティの変更などが自動で行われた。

@tailwind base;
@tailwind components;
@tailwind utilities;
@import 'tailwindcss';
absolute right-3 rounded
absolute right-3 rounded-sm

Error: Missing field negated on ScannerOptions.sources#

しばらく経ってから別の環境でアップグレードを実行したところ、次のエラーが発生した。

Terminal window
$ npx @tailwindcss/upgrade@next
# ...
Error: Missing field `negated` on ScannerOptions.sources

これは次のようにアップグレードコマンドを変更して実行することで回避できた。

Terminal window
npx @tailwindcss/upgrade@latest

非推奨になった@astrojs/tailwind の削除#

@astrojs/tailwindは v6 で非推奨になり、Tailwind の公式ドキュメントに記載された方法が推奨されるようになった。

https://github.com/withastro/astro/blob/HEAD/packages/integrations/tailwind/CHANGELOG.md#600

次のドキュメントの記載されている通りに、作業を進めた。

https://tailwindcss.com/docs/installation/framework-guides/astro

Terminal window
pnpm add @tailwindcss/vite
 import { defineConfig } from "astro/config";
 import tailwind from "@astrojs/tailwind";
 import tailwindcss from "@tailwindcss/vite";


export default defineConfig({
  integrations: [
    tailwind()
  ],
  vite: {
    plugins: [
     tailwindcss()
    ],
  },
});

Cannot apply unknown utility class エラー#

独自に定義したユーティリティを@applyで使用している箇所で、Cannot apply unknown utility classエラーが発生しているように見えた。

（今回アップグレードを実行したサイトでは、使用したテンプレートで多くの@applyが使用されていた）

いくつか同様の issue が報告されているが、次の issue が最も関連していると思われる。

https://github.com/tailwindlabs/tailwindcss/issues/15778

@referenceの使用などが提案されている。

明示的ではないが非推奨寄りな@apply#

Tailwind の作者（Adam Wathan）は、@applyに対して以前から否定的な意見を述べている。

私自身も、@applyの使用に消極的な意見を持っているので、今回は元々テンプレートに記載されていた@applyを削除して対応した。

Config ファイルのテーマが効いていない#

@applyの削除によりエラーは出なくなったが、いくつかのスタイルが適用されていないことに気がついた。

効いていないスタイルは全て、次のようにtailwind.config.jsに記載されているものであった。

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    screens: {
      sm: "640px",
    },
    extend: {
      maxWidth:{
        prose: "80ch",
      },

アップグレードガイドなどを見ても、これが利用できなくなるという記述は見受けられなかったが、Tailwind v4 で追加された@themeディレクティブを利用して解消した。