Astroで作ったサイトのtailwindcssをv3からv4にアップグレードする

Astroで作ったサイトのtailwindcssをバージョン3からバージョン4にアップグレードしたので、そのメモ。 以前tailwindcss以外も一気にアップグレードしたらエラー地獄に陥ってずっとアップグレードするのを避けていたが、そろそろしなければと思いastroとTailwindのアップグレードガイドを見ながらやってみました。

Tailwind4を追加する

まず、astroのバージョンが5.2.0以下の時に npx astro add tailwind コマンドを使用しているならVite Tailwindプラグインはインストールされていないので npm install @tailwindcss/vite で手動でVite Tailwindプラグインを追加すること。

その後src/styles/以下にglobal.cssを作成して（ファイル名は何でも良い）以下を追加

@import "tailwindcss";

tailwindを全てのページに適応したいので私の場合はsrc/layouts/Layout.astroに以下を追加

import "../styles/global.css";

@astrojs/tailwindのアンインストール

tailwindv3では@astrojs/tailwindインテグレーションを使用していましたが、v4では不要なのでアンインストール

npm uninstall @astrojs/tailwind

astro.config.mjsの修正

@astrojs/tailwindに関連する物をastro.config.mjsから削除してVite Tailwindプラグインを追加します。

- import tailwind from '@astrojs/tailwind';
+ import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
-  integrations: [ tailwind()],
+  integrations: [],
  output: "server",
  adapter: cloudflare(),
  cacheDir: "./cache",
+  vite: {
+   plugins: [tailwindcss()],
+ },
});

これでTailwind4をAstroで使用できるようになりました。

@applyを使用している場合は

上記の通りにTailwind v4の設定をしても@applyを使用していると

Cannot apply unknown utility class `pl-4`. Are you using CSS modules or similar and missing `@reference`? https://tailwindcss.com/docs/functions-and-directives#reference-directive

とエラーが出ます。エラーメッセージのurlを見てみると

Vue や Svelte コンポーネントの ブロック内、または CSS モジュール内で @apply や @variant を使用する場合は、テーマ変数、カスタムユーティリティ、カスタムバリアントをインポートして、そのコンテキストでそれらの値を使用できるようにする必要があります。 出力に CSS を重複させずにこれを行うには、@reference ディレクティブを使用して、実際にスタイルを含めずに、参照のためにメインのスタイルシートをインポートします：

と書いてあるので

<style is:global>
+  @reference "../styles/global.css";
  .markdown-body ul {
    @apply list-disc list-inside pl-4 mb-4;
  }
  .markdown-body h1,
  h2,
  h3 {
    @apply font-bold mb-4;
  }
  // ...
</style>

と@reference "../styles/global.css";を追加することでエラーは無くなりました

参照
Astro： Tailwind
Tailwindcss: Install Tailwind CSS with Astro
Tailwindcss: @reference