🐝

Astro + Vite + vanilla-extract で CSS の HMR が動かない問題

に公開
Vite
Astro
vanilla-extract
hmr
tech

CSS を書いてモジュールとして使う方がクラス名をいっぱい付けるより好きなので vanilla-extract css を好んで使っています。
https://vanilla-extract.style/

今回 Astro (vite) のプロジェクトに vanilla-extract を導入したのだが、開発中のホットリロードで vanilla-extract の .css.ts の変更は感知されるのに CSS が更新されない問題が発生たのでそのメモです

📦 packages

  • astro: ^5.16.5
  • vite: ^6.4.1
  • @vanilla-extract/css: ^1.17.5
  • @vanilla-extract/vite-plugin: ^5.1.3

🚀 設定ファイル

公式ドキュメントにある方法のままです

astro.config.mjs
import { defineConfig } from "astro/config";
import tsconfigPaths from "vite-tsconfig-paths";

// https://astro.build/config
export default defineConfig({
  output: "static",
  vite: {
    plugins: [tsconfigPaths(), vanillaExtractPlugin()],
  },
  integrations: [react()],
});

参考: https://vanilla-extract.style/documentation/integrations/astro/

🐝 vanilla-extract の CSS が HMR で更新されない問題

CSS (vanilla-extruct)

src/styles/index.css.ts
import { style } from "@vanilla-extract/css";

export const main = style({
  backgroundColor: "#666",
});

HTML (astro)

src/pages/index.astro
---
import { main } from "@/styles/index.css";
---
<html>
  <head>...</head>
  <body>
    <main class={main}>...</main>
  </body>
</html>

npm run dev で DEV サーバーを起動し、index.css.ts を更新すると変更が感知されホットリロードされるのだが、 CSS の変更が反映されない状態。astro ファイルを更新しても変化はない。
DEVサーバーを止めて再度 npm run dev しない限り CSS module が更新されないという状態で、この状態ではとてもスムーズに開発を進められる状態ではありませんでした 😭

HMR が壊れてるバグ報告...

修正 PR もマージされているのだが @vanilla-extract/vite-plugin@5.1.3 ではうまく動作してない状況だった

❇️ @vanilla-extract/vite-plugin のバージョンを固定することで解決した

Please try out this snapshot version: @vanilla-extract/vite-plugin@5.1.2-vite-hmr-fix-20250826075423. In my testing it seems to have fixed the HMR issue in Astro, as well as generally improved HMR by reducing unnecessary invalidations.
https://github.com/vanilla-extract-css/vanilla-extract/issues/1621#issuecomment-3226995345

package.json
{
  "devDependencies": {
-   "@vanilla-extract/vite-plugin": "^5.1.3",
+   "@vanilla-extract/vite-plugin": "@vanilla-extract/vite-plugin": "5.1.2-vite-hmr-fix-20250826075423",
  }
}

5.1.3 でも HMR が動作しない報告があり、同様の現象だった。
根本解決には至ってないのか、他のパッケージやフレームワークの問題なのか判断しかねるが、 issue のコメントにあったプラグインのバージョンを固定することで vanilla-extract の CSS がホットリロードで更新されるようになりました 🎉

[参考]
https://vanilla-extract.style/documentation/integrations/astro/
https://github.com/vanilla-extract-css/vanilla-extract/issues/1621#issuecomment-3226995345
https://astro.build/
https://zenn.dev/kikiki_kiki/articles/920c0c7fba083e

Discussion