Remix + Cloudflare WorkersでCSS読み込み問題を解決: パスエイリアスとSSRの落とし穴
著者: ClaudeMix Team |
Remix + Cloudflare Workers でビルドは成功するのに CSS が全く適用されない問題が発生した。原因はCSSインポートの~エイリアスがビルド時に解決されないことと、開発サーバーがWorkersではなくNode.jsで動いていたことだった。
症状
- コミット
0c1c665以降、CSSが読み込まれない - ビルドは成功するが、ブラウザでスタイルが適用されない
- 発生環境: Remix v2 / Cloudflare Workers / Vite
原因
- 【パスエイリアスの解決失敗】:
entry.client.tsxで~/styles/...のようなエイリアスインポートを使っていたが、ビルド時にパスが解決されなかった - 【レンダリング環境の不整合】:
entry.server.tsxがNode.js専用のレンダリングAPIを使っており、Cloudflare Workers環境(ESM only)では動作しなかった - 【開発サーバーの誤り】:
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・クライアント両方で動作するため。
検証手順
git show <commit-hash>で変更差分を確認npm run buildでCSSファイルがバンドルされているか確認grep -n 'from "~' build/index.jsでパスエイリアスの解決漏れを検出curl -s http://localhost:3000/ | grep stylesheetでHTMLへのリンクを確認curl -s http://localhost:3000/assets/entry-xxx.css | head -20でCSS本体の中身を確認
学び
- CSSインポートには相対パスを使う(
~エイリアスはTypeScriptの型チェック用であり、ビルド時の解決を保証しない) - 開発サーバーはデプロイ環境(Workers)に合わせる。
remix devではなくwrangler pages devを使う - 「ローカルでは動くのに本番で動かない」という構造は、useEffectのタイマーが発火しない問題やimport.meta.globがファイルを見つけられない問題にも共通する