掲題の通り。
目次
何気に 2026 年初エントリだ。
公式のリリース記事はこちら。
基本的に公式のアップグレードガイドに沿って更新していく。
公式の推奨は、公開されている @tailwindcss/upgrade
パッケージを使ってアップグレードすること。
pnpm dlx @tailwindcss/upgrade
的に。
しかし VitePress のディレクトリ構成が特殊だからなのか、うまいこと動いてくれず、下記のようなエラーが出てしまった。
% pnpm dlx @tailwindcss/upgrade@next
≈ tailwindcss v4.0.2
│ Searching for CSS files in the current directory and its subdirectories…
│ ↳ Could not determine configuration file for: `./node_modules/tailwindcss/base.css`
│ Update your stylesheet to use `@config` to specify the correct configuration file explicitly and then run the upgrade tool again.
│ ↳ Could not determine configuration file for: `./node_modules/tailwindcss/components.css`
│ Update your stylesheet to use `@config` to specify the correct configuration file explicitly and then run the upgrade tool again.
│ ↳ Could not determine configuration file for: `./node_modules/tailwindcss/screens.css`
│ Update your stylesheet to use `@config` to specify the correct configuration file explicitly and then run the upgrade tool again.
│ ↳ Could not determine configuration file for: `./node_modules/tailwindcss/tailwind.css`
│ Update your stylesheet to use `@config` to specify the correct configuration file explicitly and then run the upgrade tool again.
│ ↳ Could not determine configuration file for: `./node_modules/tailwindcss/utilities.css`
│ Update your stylesheet to use `@config` to specify the correct configuration file explicitly and then run the upgrade tool again.
│ ↳ Could not determine configuration file for: `./node_modules/tailwindcss/variants.css`
│ Update your stylesheet to use `@config` to specify the correct configuration file explicitly and then run the upgrade tool again.
また、レポジトリルートで実行したときは下記のエラーが発生してしまった。まあこれは残当。
% pnpm dlx @tailwindcss/upgrade@next
≈ tailwindcss v4.0.2
│ Searching for CSS files in the current directory and its subdirectories…
│ ↳ Cannot find any CSS files that reference Tailwind CSS.
│ Before your project can be upgraded you need to create a CSS file that imports Tailwind CSS or uses `@tailwind`.
│ ↳ No PostCSS config found, skipping migration.
│ Updating dependencies…
│ No changes were made to your repository.
仕方ないので、アップグレードガイドにある内容を一つずつ実行していくことにする。
v4 は vite を直接サポートするようになったので、postcss 経由で使う必要がなくなった。ただ、なにか postcss のプラグインが他に必要なのであれば、その限りではない(かもしれない。未検証)。
VitePress の場合は、 .vitepress/config.ts
で設定する。
import { defineConfig } from 'vitepress'
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
vite: {
plugins: [
tailwindcss(),
],
},
})
ちなみに @tailwindcss/vite
は現状引数での設定変更をサポートしていない。
また、私の環境では最初 @tailwindcss/vite
の型解決に失敗してしまい、 tsconfig.json
の moduleResolution
を node
から bundler
に変える必要があった。
.vitepress/config.ts
で公式プラグインを設定することにより postcss.config.js
は不要になるので削除してしまう。
v4 では CSS-first configuration になり、tailwind.config.js
が不要になった。
そのため、設定項目は @import "tailwindcss";
を書いた css ファイルに書いていくことになる。
たとえば色定義を追加している場合は
@import "tailwindcss";
@theme {
--color-amazon: #f6ce50;
}
となる。
tailwind.config.js
にてプラグインを追加していた場合は、プラグインが v4 に対応しているか否かによって対応が異なる模様。
弊ブログで使っている @tailwindcss/typography
は、2026/02/02 時点ではまだ v4 に対応していないので、下記のように @plugin
directive を使って書くことになる。
@import "tailwindcss";
@plugin "@tailwindcss/typography";
しかしこの方法では、tailwind.config.js
でプラグインの挙動をいじっていた場合はうまく移行しきれない可能性がある。
@tailwindcss/typography
の v4 対応については、こちらの issue を追えばよさそう。
@tailwindcss/typography
の公式サンプルを参考に下記のように書いていたところ、 prose
クラスをあてた要素にホバーしたタイミングで、全 a
要素のスタイルがホバーしたときのものに切り替わるようになってしまった。
「a
要素にホバーしたタイミングで、ホバーされた a
要素のスタイルのみ切り替わる」が想定する挙動であり、v3 での挙動でもあった。
<Content class="VPPost__content vp-doc prose dark:prose-invert prose-a:break-all hover:prose-a:decoration-dotted mt-8 max-w-full flex-grow" />
しかしこれの解決は簡単で、解決策付きの issue がすでに起票されていた。
OP に記載があるように、
hover:prose-a:decoration-dotted
を
prose-a:hover:decoration-dotted
に変えてあげれば良い。
OP も言ってるけど、たしかにこれ修正後のほうが正しい気がしてしまう。
いくつかのクラスがリネームされたり非推奨になったりしている。
この辺を見つつ書き換えれば良い。
@apply
が効かない アップグレードガイドの Using @apply with Vue, Svelte, or CSS modules と issue にある Unable to use the @apply in vue scoped css. · Issue #15717 · tailwindlabs/tailwindcss が参考になる。
v4 では Vue コンポーネントに直接書かれた style とメインの CSS は個別にバンドルされる。 そのため theme の各種変数やユーティリティにアクセスできず、結果として @apply
に失敗してしまう。
これを回避するためには @reference
directive を使って、メインの CSS ファイルを参照する必要がある、ということらしい。
<template>
<h1>Hello world!</h1>
</template>
<style>
@reference "../../style.css";
h1 {
@apply text-2xl font-bold text-red-500;
}
</style>
つまりこういうこと。いかにも煩雑だが、@apply
しない場合は不要なようなので、影響があるのはサードパーティライブラリを使用するごく一部のコンポーネントに限られる気はする。