1. JSS Next.jsアプリとSitecoreエディタを統合するためのアーキテクチャとAPI

ウォークスルー
.js JSSアプリをSitecore編集者に接続する

Version:
日本語翻訳に関する免責事項

このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。

Sitecoreコンテナテンプレートを使ってNext.js JSSアプリケーションを作成すると、Next.jsアプリはSitecoreエディターとの統合が事前に設定されています。しかし、JSS CLIでアプリを作成した場合は、Sitecoreエディターとの統合を手動で設定する必要があります。

Next.js JSSアプリをSitecore編集者に接続する前に、以下の条件を満たす必要があります:

JSSアプリケーションを接続したら、Next.js JSSアプリケーションをSitecore Experience EditorやHorizonなどのSitecoreエディタと連携させることができます。

このウォークスルーでは、以下の方法を説明します:

  • JSSアプリのSitecore設定パッチを更新してください。
  • Sitecoreエディタのエンドポイントを安全にしてください。
  • Next.jsアプリケーションを設定してください。

!注Next.js用のSitecoreコンテナテンプレート は、エクスペリエンスエディターとの事前設定された統合を提供します。

JSSアプリのSitecore設定パッチを更新してください

コードファーストのNext.jsアプリケーションで高度なSitecoreエディタとの統合を有効にするには、まずSitecoreの設定パッチを使ってJSSアプリケーションを設定する必要があります。

Sitecoreエディタ統合に必要な設定を作成するには:

  1. Next.js JSSアプリケーションディレクトリのルートで、ファイル /sitecore/configを開きます。

  2. パスconfiguration/sitecore/javaScriptServices/apps上で、Next.jsアプリケーションのappノード上で、以下の属性を設定します。

    • serverSideRenderingEnginehttp。これはNext.jsアプリケーションがSitecoreエディタとの統合のためにHTTPレンダリングエンジンを使用しているためです。
    • serverSideRenderingEngineApplicationUrl ホスト名とポートを選んでください。デフォルト値は http://localhost:3000です。
    • serverSideRenderingEngineEndpointUrl Next.jsアプリのAPIルートの絶対URLに、Sitecoreエディターからの POST リクエストを処理するためのアドレスです。デフォルト値はRender API Route http://localhost:3000/api/editing/renderのルートです。

    デフォルト設定とデフォルト値は以下の通りです:

    ... ...

  3. ターミナルで、次のコマンドを実行して新しい構成をSitecoreインスタンスに展開します。

    jss deploy config

Sitecoreエディタのエンドポイントを安全に保つ

Next.jsアプリケーションでSitecoreページを編集モードでレンダリングする場合、SitecoreエディタのエンドポイントはNext.jsアプリ内のエディター統合APIルートを通じて公開されます。

Sitecoreエディタのエンドポイントを保護するには、まず秘密トークンを生成する必要があります。Sitecoreは 少なくとも16文字の英数字値を推奨しています。

この秘密はサーバー側とクライアント側の両方で設定し、値が一致しなければなりません。

サーバー側でJSS編集シークレットを設定するには、2つの選択肢があります。SITECORE_JSS_EDITING_SECRET環境変数を設定するか、Sitecore設定パッチでSitecoreエディタエンドポイントを保護するかです。

SitecoreエディターエンドポイントをSitecoreの設定パッチで保護するには:

  1. Next.js JSSアプリケーションディレクトリのルート、/sitecore/configファイルのノードconfiguration/sitecore/javaScriptServices/settingsで、JavaScriptServices.ViewEngine.Http.JssEditingSecretを追加またはコメント解除して設定します:

  2. ターミナルで、新しい構成をSitecoreインスタンスにデプロイします:

    jss deploy config

Next.jsアプリケーションを設定してください

Sitecoreエディタ統合のためにNext.jsアプリケーションを設定するには:

  1. プロジェクトのルートディレクトリの .envファイルで、環境変数JSS_EDITING_SECRETをサーバー側で設定したSITECORE_JSS_EDITING_SECRETの値に設定します。

  2. Sitecoreエディタで編集可能な任意のページで、useEffect Reactフック内で、まだ存在していなければユーティリティ関数 handleEditorFastRefresh呼び出してください:

    import { handleEditorFastRefresh } from '@sitecore-jss/sitecore-jss-nextjs';

    const MyPage = ({ notFound, layoutData, componentProps }: SitecorePageProps): JSX.Element => { useEffect(() => { // Refresh Experience Editor / Horizon markup and JS after Next.js Fast Refresh handleEditorFastRefresh(); }, ); ... };

    export default MyPage;

    !注Next.jsのサンプルアプリケーションには、すでにこのコードがデフォルトのキャッチオールルートに含まれています。

    Next.jsの快速リフレッシュ機能は、Sitecoreエクスペリエンスエディター内で使用する場合、いわゆるエディタークローム(Sitecoreエディターが各レンダリングごとに注入する追加のマークアップやJavaScript)を保持するために特別な扱いが必要です。

    デフォルトでは、エディターのクロームだけが更新されます。場合によっては、forceReloadパラメータを使ってページ全体を強制的に再読み込みしたい場合もあります:

    handleEditorFastRefresh(true)

統合の検証

Next.jsアプリケーションが正しく動作していることを確認するには:

  • アプリケーションのURLをブラウザで開いてください。デフォルト http://localhost:3000(http://localhost:3000) 。

トラブルシューティング

開発モードでNext.jsを実行中、動的コンパイルのために最初のページ編集時にタイムアウトが発生することがあります。しかし、その後のリクエストではこの問題は自然に解決することが期待できます。

他に問題があれば、以下の点を確認してください。

  • サーバー側とクライアント側の両方でJSS編集秘密が一致していることを確認します。
  • Next.jsのログにエラーがないか確認してください。
  • Sitecoreのログに誤りがないか確認してください。

!ヒントJSSデバッグロガー を使って、Next.jsアプリ内のSitecoreエディタ連携をデバッグしてください。

この記事を改善するための提案がある場合は、 お知らせください!