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

1
npx @tailwindcss/upgrade@next

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

1
@tailwind base;
2
@tailwind components;
3
@tailwind utilities;
4
@import 'tailwindcss';

1
absolute right-3 rounded
2
absolute right-3 rounded-sm

1
$ npx @tailwindcss/upgrade@next
2
# ...
3
Error: Missing field `negated` on ScannerOptions.sources

1
npx @tailwindcss/upgrade@latest

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

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

• #13049 2ed4bd9 Thanks @florian-lefebvre! - Deprecates the integration

  Tailwind CSS now offers a Vite plugin which is the preferred way to use Tailwind 4 in Astro. Please uninstall @astrojs/tailwind and follow the [Tailwind documentation for manual installation] (https://tailwindcss.com/docs/installation/framework-guides/astro).

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

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

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

1
pnpm add @tailwindcss/vite

1
 import { defineConfig } from "astro/config";
2
 import tailwind from "@astrojs/tailwind";
3
 import tailwindcss from "@tailwindcss/vite";
4

5
export default defineConfig({
6
  integrations: [
7
    tailwind()
8
  ],
9
  vite: {
10
    plugins: [
11
     tailwindcss()
12
    ],
13
  },
14
});

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に対して以前から否定的な意見を述べている。

• https://x.com/adamwathan/status/1226511611592085504
• https://x.com/adamwathan/status/1559250403547652097

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

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

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

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

1
/** @type {import('tailwindcss').Config} */
2
module.exports = {
3
  theme: {
4
    screens: {
5
      sm: "640px",
6
    },
7
    extend: {
8
      maxWidth:{
9
        prose: "80ch",
10
      },

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