SSR support and related enhancements in Web Awesome
Web Awesome now provides optional server‑side rendering (SSR) across its documentation site and component demos, exposing user‑controlled toggles, cookie persistence, and updated build pipelines to enable a seamless SSR experience without breaking existing client‑side rendering.
背景
SSR が求められる背景には、SEO の向上と初回ロード時間短縮という要件がある一方、既存のクライアント‑サイド実装との互換性を保つ必要があった。PR #2428 では、Issue #1861 の HasSlotController に対するサーバー環境チェックや、Issue #2369 のスロット描画不具合を解消しつつ、SSR のフラグ管理と UI 切替機能を追加した。
技術的な変更
GitHub Actions ワークフロー が push と pull_request の next ブランチで走るよう拡張され、SSR テスト用ジョブが有効化された。
パッケージバージョン が更新され、@lit-labs/eleventy-plugin-lit が 1.0.3 → 1.0.6、@lit-labs/ssr が 3.x → 4.x に上げられ、SSR 用の依存関係が最新に揃えられた。
Eleventy 設定 (packages/webawesome/docs/.eleventy.js) に isDev 判定と serverBuild フラグに加えて、globalData に isDev と ssr の情報が注入され、SSR の有効化を環境変数 SSR で制御できるようになった。条件分岐の内部で globalThis.litSsrCallConnectedCallback = true; を設定し、connectedCallback が SSR コンテキストでも呼び出される保証を追加した。
テンプレート変更:
- base.njk で wa-cloak クラスを SSR 時に除外し、テーマ/パレットクッキーのサーバー側取得を支援した。
- head.njk に <script type="module" src="/dist/webawesome.ssr-loader.js"></script> を挿入し、SSR ローダーを常時ロード。
- 新規テンプレート ssr-switch.njk を作成し、wa-switch と SSR 説明ボタン/ツールチップを提供。クッキー webawesome_ssr の永続化ロジックは head.njk の setCookie / removeCookie 関数で実装された。
- nav-products.njk、sidebar.njk などの UI 位置に ssr-switch.njk を組み込み、ユーザーが UI から SSR のオンオフを切り替えられるようにした。
- component.njk に SSR セクションを追加し、コンポーネントが SSR に対応しているかを自動的に表示できるようにした。
カスタム要素マニフェスト (custom-elements-manifest.js) に ssr タグを許容する配列要素を追加し、SSR 用メタ情報を文書化できるようにした。
テーマクッキー の保存ロジックが theme.js に統合され、ブランド・パレット・テーマの変更が Cookies に永続化され、SSR 後のリクエストでも同一テーマが再現できる。
ハイドレーションエラー可視化 (hydration-errors.js) が非同期 import に変更され、エラー処理が遅延ロードで実行されるよう最適化された。また CSS (hydration-errors.css) が差分表示用のスタイルを追加し、挿入・削除箇所が緑・赤でハイライトされるようになった。
設計判断
SSR のオプトイン方式 として UI スイッチとクッキーを採用したのは、既存のクライアント‑サイド利用者への影響を最小化しつつ、開発者がサーバー側レンダリングを手軽に試せるデザイン選択である。base.njk の条件分岐で wa-cloak を除外し、SSR 時の FOUC を防止する点も、ユーザー体験を保護する意図が明確だ。
依存バージョンの一括更新 は、Lit の SSR エコシステム全体を同一メジャーバージョンへ合わせることで、将来の破壊的変更リスクを減らす方針と合致している。@lit-labs/ssr が 4.x になることで、@lit-labs/ssr-dom-shim の互換性も向上し、SSR 用ビルドが安定化した。
カスタムマニフェスト拡張 は、SSR 対応情報を自動生成ドキュメントに埋め込む手段として、設計上の一貫性を保ちつつメンテナンスコストを抑える選択である。ssr タグを既存の customTags に追加するだけで、追加のスキーマ変更を回避できた。
まとめ
この PR は、Web Awesome に SSR のスイッチング機構とサーバー側レンダリング支援を導入し、開発者とエンドユーザー双方に安全かつ柔軟な SSR 体験を提供する。既存のクライアント‑サイド実装はそのまま動作し、テーマ・パレット設定もサーバーで保持できるため、今後のドキュメントやアプリケーションで SSR を段階的に拡張できる基盤が整った。