Docusaurusのサイトに「kifu for JS」を使った将棋盤を埋め込みたいものの、うまく動作せず困ってしまうケースは少なくありません。特にReactベースのDocusaurusでは、通常のHTML埋め込みとは挙動が異なるため、スクリプトの扱いでつまずきやすいポイントがあります。本記事では、Docusaurus環境で将棋盤を正しく表示・動作させるための基本構成と、動かない原因の切り分け方法について整理します。
kifu for JSがDocusaurusで動かない主な理由
DocusaurusはReactベースの静的サイトジェネレーターであり、通常のHTML＋JavaScriptの直接埋め込みとは動作方式が異なります。
そのため、kifu for JSのような外部スクリプトをそのまま貼り付けても、DOMの生成タイミングやスクリプトの読み込み順の問題で動作しないことがあります。
特にwindowオブジェクト依存のスクリプトはSSR（サーバーサイドレンダリング）との相性で問題が起きやすいです。
基本的な埋め込み方法の考え方
Docusaurusでは、単純なscriptタグの貼り付けではなく、Reactコンポーネントとして扱う必要があります。
kifu for JSの初期化コードは、useEffectなどを使い「クライアント側でのみ実行」するように制御するのが基本です。
これによりSSR時のエラーや未定義オブジェクトの問題を回避できます。
Reactコンポーネントとしての実装例の考え方
将棋盤を表示する領域をdivで用意し、useRefでDOMを取得して初期化処理を行う構成が一般的です。
例えば「useEffect内でkifuの初期化関数を呼ぶ」ことで、ページ描画後に安全にスクリプトを実行できます。
また、外部JSファイルはdocusaurus.config.jsやclientModuleとして読み込む方法もあります。
よくある失敗パターン
最も多いのは、HTMLファイルのコードをそのままMarkdownやMDXに貼り付けてしまうケースです。
この場合、スクリプトが実行されず単なるテキストとして扱われるか、ビルド時にエラーになることがあります。
また、window未定義エラーはSSR環境で頻繁に発生する典型的な問題です。
解決のためのチェックポイント
まず「ブラウザ側でのみ実行されているか」を確認することが重要です。
次に、kifu for JSの読み込み順序が正しいか、CDNが正しく参照されているかをチェックします。
さらに、Reactコンポーネントとして分離できているかどうかも重要なポイントです。
まとめ
Docusaurusでkifu for JSを動かすには、単純なHTML埋め込みではなくReactのライフサイクルに合わせた実装が必要になります。
特にSSRとクライアントサイド実行の違いを理解することが重要であり、useEffectを使った制御が基本となります。
構造を正しく設計すれば、Docusaurus上でも安定して将棋盤を表示することが可能です。
コメント