Summary
この文書の要点
- 最初は見た目を変えずにビルド管理へ移す。
- 画像、CSS、JavaScriptの参照パスを整理する。
- HTML、CSS、JavaScript、画像の参照を整理し、ビルドで壊れたリンクを検出できるようにする。
- 段階移行では、既存URLを保ちつつページ単位でVite管理へ移す。
どこが設計の難所か
手書きHTMLが増えると、共通ヘッダーの修正漏れ、画像パスの散乱、CSSの重複、不要ファイルの残存が起きます。ただし、安定しているサイトを一度にフレームワーク化するとリスクが上がります。
既存サイトには検索評価、外部リンク、印刷物のQRコードなどが紐づいていることがあります。URL構造やメタデータを不用意に変えると、技術的には動いても運用上の問題になります。
長く運用された静的HTMLサイトでは、コピーされたCSS、未使用JavaScript、相対パス、手動圧縮画像が混ざりがちです。見た目が動いていても、変更時にどこへ影響するか分かりにくくなります。
境界をどう切るか
第一段階では、Viteでビルドできる構成へ移し、HTMLの内容とURLはできるだけ保ちます。次に共通CSS、画像最適化、共通部品化を進めます。必要になるまでReact化しない判断もあります。
設計では、まず現行URL、共通パーツ、アセット、フォーム、外部スクリプトを棚卸しします。Viteへ移す時は、URL構造を維持しながら、共通CSSやJSをモジュール化し、ビルド成果物として配信できる状態にします。
実装で効く細部
Viteのエントリを整理し、public配下とビルド対象アセットを分けます。CSSはグローバルな基礎スタイルとページ固有スタイルに分け、JavaScriptは必要なページだけで読み込みます。
Viteでは、ページごとのentry、共通CSS、画像import、静的public配置を整理します。既存HTMLを一度にReact化するのではなく、必要なページだけコンポーネント化し、単純なページはHTMLに近い形で残す判断も有効です。
- 既存URLとリダイレクトを先に一覧化し、移行でリンク切れを出さない。
- publicに置く資産とimportしてハッシュ管理する資産を分ける。
- ビルド後のHTMLを確認し、title、description、OGP、canonicalが維持されているか見る。
壊れ方を観測する
検証では、全ページのリンク、画像、OGP、フォーム、404、モバイル表示を移行前後で比較します。ビルド後のdistをローカルpreviewで確認し、相対パスが壊れていないかを見ます。
検証では、代表ページの表示、画像、フォーム、リンク、メタタグ、404を確認します。リンクチェッカーやPlaywrightで主要導線を回すと、手作業では見落としやすい相対パスの問題を拾えます。
捨てた選択肢とトレードオフ
Viteに移しても、共通部品化をしなければ重複は残ります。一方で、最初から大きく作り替えると公開リスクが高くなります。段階移行で安定性を優先する方が適することがあります。
すべてを一気にSPA化すると移行コストが大きくなります。Vite管理にするだけでも、ビルド、依存管理、アセット最適化の恩恵はあります。目的に応じて、静的HTMLのまま改善する範囲を残す判断が重要です。
現場に残す判断軸
静的HTMLの近代化は、フレームワーク導入ではなく管理方法の改善から始められます。URLと見た目を守りながらビルド管理へ移すことで、後の改善が進めやすくなります。
静的サイトのモダン化は、全面リニューアルでなくても進められます。URLを保ち、ビルドで再現できる状態にするだけで、保守性は大きく改善します。
