[Tailwind CSS v4] 設定ファイルなしで Astro に導入する

Astro へ移行するついでに、スタイルを Tailwind CSS v4 で組み直しました。 v4 は v3 までと考え方がけっこう変わっていて、tailwind.config.js が無くても動くのが新鮮だったのでメモしておきます。

インストール

Astro では Vite プラグイン版（@tailwindcss/vite）を使うのが手軽です。記事本文の整形に Typography プラグインも入れておきます。

npm i tailwindcss @tailwindcss/vite @tailwindcss/typography

astro.config に Vite プラグインを足す

v3 までの @astrojs/tailwind インテグレーションではなく、Vite プラグインとして登録します。

// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';

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

CSS は @import 'tailwindcss'; 1行から

v4 では @tailwind base; などのディレクティブが廃止され、@import 'tailwindcss'; の1行になりました。プラグインも CSS 側で @plugin で読み込みます。

/* src/styles/global.css */
@import 'tailwindcss';
@plugin '@tailwindcss/typography';

あとはこの CSS をレイアウトで読み込むだけ。

---
// src/layouts/BaseLayout.astro
import '@/styles/global.css';
---

テーマは @theme で。config ファイルは不要

ここが一番の変化点。v3 では tailwind.config.js の theme.extend で色やフォントを定義していましたが、v4 は CSS の @theme ブロックに CSS 変数として書くだけです。

@theme {
  --color-primary: #4865B2;
  --color-text: #464646;
  --color-bg: #F7F7F7;

  --font-sans: 'Avenir', 'Noto Sans JP', 'Hiragino Sans', sans-serif;
}

こう定義すると、bg-primary や text-primary、font-sans といったユーティリティが自動で生えてきます。tailwind.config.js は作っていません。

任意の場所で CSS 変数として参照することもできます。

<div class="bg-[var(--color-bg)] text-[var(--color-text)]">...</div>

記事本文は prose で

Typography プラグインの prose クラスで Markdown 本文をいい感じに整形できます。ダークモード対応の dark:prose-invert も付けておくと楽です。

<div class="prose prose-lg dark:prose-invert max-w-none">
  <slot />
</div>

ハマりどころ・メモ

• v3 のつもりで @tailwind base; と書くと動かない。@import 'tailwindcss'; に置き換える。
• プラグインは package.json に入れるだけでなく、CSS 側で @plugin する必要がある。
• 色やフォントは @theme に CSS 変数で定義 → ユーティリティが自動生成される。tailwind.config.js を探し回らなくて良いのは思った以上に快適だった。
• Astro では @astrojs/tailwind ではなく @tailwindcss/vite を使う（v4 の推奨）。

設定ファイルが消えて、色の定義も CSS にまとまったので、見通しがかなり良くなりました。