O hirunewani blog

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

Created at

現在ブログとして運用しているサイトの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

npx @tailwindcss/upgrade@next

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

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

非推奨になった@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

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ディレクティブを利用して解消した。