Astro製のブログで使っているTailwindCSSをv4にアップグレードする

はじめに

少し前にTailwindCSSのv4がリリースされ、自分のポートフォリオサイトの方は対応した。

Svelte + Vite環境のサイトのTailwindCSSをv4にアップグレードした話と@applyへの考え方の変化 | okaryo.log

コンポーネント設計大事

blog.okaryo.studio

Astroで作っているこのブログも早くv4に更新したいなと思いつつ、プラグインの@astrojs/tailwindが対応されるのを待っていた。すると先日、プラグインの方でv4に対応したPullRequestがマージされた。この変更内容を見て気づいたが、TailwindCSSのv4ではViteプラグインを提供するようになったので@astrojs/tailwindは不要であり、プラグインの更新を待つ必要はなかった。

というわけでこのブログでも早速TailwindCSSをv4にアップグレードしたので対応内容を残しておく。

対応内容

依存関係のセットアップ

まずは、新しく使うことになるプラグインの@tailwindcss/viteをインストールする。

npm install @tailwindcss/vite

今まで使っていた@astrojs/tailwindは削除する。一応v6としてメジャーバージョンがリリースされているが、これは既存プロジェクトが新しいプラグインに移行するまでの利便性のためで、今後新しい機能が提供されることはないとのことだ。

npm rm @astrojs/tailwind

astro.config.mjsの変更

次はastro.config.mjsで使用するプラグインを@astrojs/tailwindから@tailwindcss/viteに変更する。また、@tailwindcss/viteを指定する箇所はintegrationsではなく、vite.pluginsなので注意。

import { defineConfig } from "astro/config";
// import tailwind from "@astrojs/tailwind"; // 削除
import tailwindcss from "@tailwindcss/vite"; // 追加

export default defineConfig({
  integrations: [
    // tailwind(), // 削除
  ],
  vite: {
    plugins: [
      tailwindcss(), // 追加
    ],
  },
})

tailwind.config.mjsとメインCSSの変更

TailwindCSSのv4からtailwind.config.mjsは不要となり、CSSファイルに直接設定を書けるようになった。TailwindCSSを読み込むためのファイルをsrc/styles/app.cssに作成(ファイル名はなんでも良い)し、tailwind.config.mjsから設定を移行する。

/* 必須: tailwindcssを読み込む */
@import "tailwindcss";

/* 任意: @tailwindcss/typographyをプラグインとして使用しているので読み込む */
@plugin "@tailwindcss/typography";

/* 任意: 移行が面倒な場合は以前のconfigファイルを読み込むことも可能 */
@config "../../tailwind.config.mjs";

/* ここにtailwind.config.mjsで書いていた設定を移動させる */

最後に、このファイルを使用する箇所で読み込む。自分の場合はBaseLayout.astroが全てのページで共通のレイアウトなので、そこで読み込ませた。

import "../styles/app.css";

@applyを使用している場合の対応

この状態で開発サーバーを起動すると、@applyを使っているファイルでError: Cannot apply unknown utility classというエラーが出る。

TailwindCSSのv4からはメインのCSSファイルとは別にバンドルされるスタイルシートから、Tailwindのテーマ変数、カスタムユーティリティ、カスタムバリアントが参照できなくなった。そのため、Astroを含めてSvelteやVueなどのSingleFileComponent(SFC)の<style>ブロック内で@applyを使用する場合は、@referenceを使ってメインのCSSファイルを明示的に参照する必要がある。

Upgrade guide - Getting started

Upgrading your Tailwind CSS projects from v3 to v4.

tailwindcss.com

以下のようにして@referenceを使って、TailwindCSSを読み込んでいるCSSファイルを読み込と正常に@applyを使用することができる。

<div class="text-class">
  <p>text</p>
</div>

<style>
@reference "../../styles/app.css";

.text-class {
  @apply p-2;
}
</style>

以上でAstro製のブログをTailwindCSS v4にアップグレードすることができた。

おわり

今までTailwindCSは基本的な使い方やユーティリティを調べて使うくらいしか活用していなかったが、今回の対応でアップグレードガイドや公式ドキュメントを読み進めるうちに今まで自分はちゃんとTailwindCSSを使い切れていなかったと感じた。ドキュメントをしっかり読んで、より適切なコンポーネントやスタイルの設計に取り組んでいきたい。