Remix + Cloudflare WorkersでCSS読み込み問題を解決: パスエイリアスとSSRの落とし穴

著者: ClaudeMix Team |

Remix + Cloudflare Workers でビルドは成功するのに CSS が全く適用されない問題が発生した。原因はCSSインポートの~エイリアスがビルド時に解決されないことと、開発サーバーがWorkersではなくNode.jsで動いていたことだった。

症状

  • コミット 0c1c665 以降、CSSが読み込まれない
  • ビルドは成功するが、ブラウザでスタイルが適用されない
  • 発生環境: Remix v2 / Cloudflare Workers / Vite

原因

  1. 【パスエイリアスの解決失敗】: entry.client.tsxで~/styles/...のようなエイリアスインポートを使っていたが、ビルド時にパスが解決されなかった
  2. 【レンダリング環境の不整合】: entry.server.tsxがNode.js専用のレンダリングAPIを使っており、Cloudflare Workers環境(ESM only)では動作しなかった
  3. 【開発サーバーの誤り】: remix devはNode.js環境で実行されるため、本番のWorkers環境とレンダリング挙動が一致していなかった

解決策

// app/entry.client.tsx
- import "~/styles/globals.css";
+ import "./styles/globals.css";
// package.json
- "dev": "remix dev",
+ "dev": "npm run build && wrangler pages dev ./build/client --compatibility-flag=nodejs_compat --port=3000",

entry.server.tsxをCloudflare Workers向け(renderToReadableStream)に統一し、wrangler pages devで開発時からWorkers環境と一致させた。

環境 レンダリングAPI モジュールシステム
Node.js renderToPipeableStream CommonJS/ESM
Cloudflare Workers renderToReadableStream ESM only

試して却下した方法

CSSインポート方法は他に2つ検討し、いずれも採用しなかった。

  • 【root.tsxのlinks関数】(Remix公式推奨): import globalStyles from "~/styles/globals.css?url" は動作するが、?urlクエリパラメータの扱いとルートごとのパス解決が複雑になり、今回の規模には見合わなかった
  • 【globals.cssでの@import】: @import './service-name/layer2.css' はViteがfileローダーで処理しようとしてCSSとして認識されず、エラーになった

最終的にentry.client.tsxでの相対パスインポート(方法A)を採用した。理由はシンプルで、Viteが自動的にバンドルし、SSR・クライアント両方で動作するため。

検証手順

  1. git show <commit-hash> で変更差分を確認
  2. npm run build でCSSファイルがバンドルされているか確認
  3. grep -n 'from "~' build/index.js でパスエイリアスの解決漏れを検出
  4. curl -s http://localhost:3000/ | grep stylesheet でHTMLへのリンクを確認
  5. curl -s http://localhost:3000/assets/entry-xxx.css | head -20 でCSS本体の中身を確認

学び