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

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

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

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

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

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

JSSアプリケーションに接続すると、Next.js JSSアプリケーションをSitecoreエディター(Sitecore Experience Editor)と連携させることができます。

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

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

!注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 Routehttp://localhost
      /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 markup and JS after Next.js Fast Refresh handleEditorFastRefresh(); }, ); ... };

    export default MyPage;

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

    Next.jsの快速リフレッシュ機能は、Sitecore Experience Editor内で特別な処理が必要で、各レンダリングごとにSitecoreエディターから注入される追加のマークアップやJavaScript(しばしばエディタークロームと呼ばれる)を保持する必要があります。

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

    handleEditorFastRefresh(true)

Next.jsでtrailingSlashが有効になっているときにJSSアプリを設定してください

Next.js trailingSlash設定オプションを有効にしている場合、JSSアプリのSitecore設定はその後のリダイレクト動作を考慮しなければなりません。そうでなければ、アプリをSitecoreに展開した後にエクスペリエンスエディターを開くと、以下のエラーが表示されます。

Connection to your rendering host failed with a Permanent Redirect error. Ensure the POST endpoint at URL http://localhost:3000/api/editing/render has been enabled.

このエラーを防ぐために:

  1. Next.jsアプリのSitecore設定パッチファイルで、serverSideRenderingEngineEndpointUrl設定をトレーリングスラッシュを含めるように変更してください。例えば、serverSideRenderingEngineEndpointUrl="http://localhost:3000/api/editing/render" からserverSideRenderingEngineEndpointUrl="http://localhost:3000/api/editing/render/"へ。

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

    jss deploy config

統合の検証

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

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

  2. エクスペリエンスエディターでページを開き、変更を加えてください。

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

もし問題が発生した場合:

  • JSSデバッグロガーを使って、Next.jsアプリ内のSitecoreエディタ連携をデバッグしてください。これにより、あなたが経験している問題の原因を特定する手助けになります。
  • Next.js JSSアプリケーションについては、当社の一般的なトラブルシューティングガイドをご覧ください。
  • サーバー側とクライアント側の両方でJSS編集秘密が一致しているか確認してください。
  • Sitecoreのログに誤りがないか確認してください。
この記事を改善するための提案がある場合は、 お知らせください!