できない.dev

Tailwind CSS v4 で PostCSS 設定がエラーになる

Tailwind v4 は PostCSS プラグインを別パッケージ @tailwindcss/postcss に分離した。postcss.config.js で tailwindcss: {} のままだとエラーになるため、@tailwindcss/postcss に置き換える必要がある。

#v4 #postcss #config #migration

公開: 更新:

実行例あり（2026-08-27 に実環境で検証）

要約

Tailwind v3 から v4 に上げた直後にビルドで It looks like you're trying to use tailwindcss directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package と出るのは、v4 が PostCSS プラグインを @tailwindcss/postcss に分離したためです。
設定ファイルを移行ガイドどおりに書き換えます。

npm i -D @tailwindcss/postcss
// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

実行例

実際に node:20 で動かすと、tailwindcss をそのまま PostCSS プラグインに指定した時点で 「The PostCSS plugin has moved to a separate package」と出て終了コード 1 で止まり、@tailwindcss/postcss に差し替えると終了コード 0 で text-3xl を含む CSS が出力される。
出力の先頭には tailwindcss v4.3.3 が入り、旧来の @tailwind ディレクティブだけを書いた CSS も同じ設定でエラーなく処理された。

$ npx postcss src/input.css -o out.css
Error: It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to continue using Tailwind CSS with PostCSS you'll need to install `@tailwindcss/postcss` and update your PostCSS configuration.
    at mt (/tmp/tmp.qZfHhLqxHT/node_modules/tailwindcss/dist/lib.js:38:1643)
    at LazyResult.runOnRoot (/tmp/tmp.qZfHhLqxHT/node_modules/postcss/lib/lazy-result.js:367:16)
    at LazyResult.runAsync (/tmp/tmp.qZfHhLqxHT/node_modules/postcss/lib/lazy-result.js:296:26)
    at LazyResult.async (/tmp/tmp.qZfHhLqxHT/node_modules/postcss/lib/lazy-result.js:198:30)
    at LazyResult.then (/tmp/tmp.qZfHhLqxHT/node_modules/postcss/lib/lazy-result.js:455:17)
    at file:///tmp/tmp.qZfHhLqxHT/node_modules/postcss-cli/index.js:255:10
    at async Promise.all (index 0)
$ echo $?
1
$ npm install --silent --save-dev @tailwindcss/postcss
$ npx postcss src/input.css -o out.css
$ echo $?
0
$ grep -c -F text-3xl out.css
5
$ head -5 out.css
/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
@layer properties;
@layer theme, base, components, utilities;
@layer theme {
  :root, :host {
$ npx postcss src/legacy.css -o legacy-out.css
$ echo $?
0

— 2026-08-27 時点の出力

検証環境

検証日
実行環境
node:20Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

よくある原因

  1. v3 のままの postcss.config.js: v3 では plugins: { tailwindcss: {}, autoprefixer: {} } で動いたが、v4 ではこの書き方はエラーになる。
  2. 古いチュートリアル: ネット上の記事は v3 ベースのものが多く、そのままコピペすると v4 で破綻する。
  3. Vite 向けの最適パスを通っていない: Vite 環境では @tailwindcss/vite プラグインに切り替えるのが推奨で、PostCSS 設定自体が不要になる。
  4. CSS エントリの書き方: @tailwind base; などの 3 つのディレクティブも @import "tailwindcss"; に統合された。

解決策

1. PostCSS 経由のままなら @tailwindcss/postcss

npm i -D @tailwindcss/postcss
// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

詳細は公式 PostCSS インストールガイド（新しいタブで開く）を参照してください。

2. Vite では @tailwindcss/vite プラグイン

npm i -D @tailwindcss/vite
// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";
 
export default defineConfig({
  plugins: [tailwindcss()],
});

このパスを通せば postcss.config.js は削除して構いません。

3. CSS エントリを統合

v4 では 3 つの @tailwind ディレクティブが 1 行にまとまりました。

/* before (v3) */
@tailwind base;
@tailwind components;
@tailwind utilities;
 
/* after (v4) */
@import "tailwindcss";

v3 → v4 の全体的な変更点は公式アップグレードガイド（新しいタブで開く）に集約されています。

この記事は役立ちましたか？