チュートリアル: Next.js JSSアプリをSitecoreエディターに接続する

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

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

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

Next.js JSSアプリをSitecoreエディターに接続する前に、次のことを行う必要があります。

JSSアプリケーションに接続すると、Next.js JSSアプリケーションをSitecoreエディタ(Sitecoreエクスペリエンスエディタなど)と統合できます。

このチュートリアルでは、次の方法について説明します。

  • 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を、SitecoreエディターからのPOSTリクエストを処理するためのNext.jsアプリのAPIルートの絶対URLに設定します。デフォルト値は、レンダリング ルート (Render API Route)http://localhost:3000/api/editing/renderのルートです。

    デフォルト値のデフォルト設定は次のとおりです。

    RequestResponse
    <configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    ...
    <javaScriptServices>
      <apps>
        <app name="exampleApp"
            ...
            serverSideRenderingEngine="http"
            serverSideRenderingEngineEndpointUrl="http://localhost:3000/api/editing/render"
            serverSideRenderingEngineApplicationUrl="http://localhost:3000"
            ...
        />
      </apps>
    </javaScriptServices>
    ...  
  </sitecore>
</configuration>

  3. ターミナルで、次のコマンドを実行して、新しい設定をSitecoreインスタンスにデプロイします。

    RequestResponse
    jss deploy config

Sitecoreエディター エンドポイントを保護する

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

Sitecoreエディターのエンドポイントを保護するには、まずシークレット トークンを生成する必要があります。Sitecoreでは、英数字の値at least 16 charactersを推奨しています。

このシークレットは、サーバー側とクライアント側の両方で設定する必要があり、値は一致する必要があります。

JSS Editing Secretをサーバー側で設定するには、2つのオプションがあります。SITECORE_JSS_EDITING_SECRET環境変数を設定するか、Sitecore構成パッチを使用してSitecoreエディターエンドポイントを保護できます。

Sitecore設定パッチを使用してSitecoreエディター エンドポイントを保護するには、次の手順に従います。

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

    RequestResponse
    <setting name="JavaScriptServices.ViewEngine.Http.JssEditingSecret" value="<YOUR_SECRET_TOKEN>" />

  2. ターミナルで、次のコマンドを実行して新しい設定をSitecoreインスタンスにデプロイします。

    RequestResponse
    jss deploy config

Next.jsアプリケーションを構成する

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

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

  2. Sitecoreエディターで編集可能な任意のページで、useEffect Reactフック内で、ユーティリティ関数handleEditorFastRefreshがまだ存在しない場合は呼び出します。

    RequestResponse
    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エディターによって挿入された追加のマークアップとJavaScriptを保持するために、Sitecoreエクスペリエンス エディター内で特別な処理を行う必要があります (多くの場合、エディター クロームと呼ばれます)。

    デフォルトでは、エディターのクロムのみが更新されます。一部のシナリオでは、forceReloadパラメーターを使用して、代わりにページ全体を強制的に再読み込みしたい場合があります。

    RequestResponse
    handleEditorFastRefresh(true)

Next.jsでtrailingSlashが有効になっている場合のJSSアプリの構成

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

RequestResponse
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インスタンスにデプロイします。

    RequestResponse
    jss deploy config

統合を確認する

Next.jsアプリケーションが正しく実行されていることを確認するには、次のようにします。

  1. アプリケーションのURLを開きます (デフォルトではブラウザー http://localhost:3000 )。

  2. エクスペリエンス エディターでページを開き、変更を加えます。

    先端

    Next.jsを開発モードで実行すると、動的コンパイルのために最初のページ編集でタイムアウトが発生する場合があります。ただし、これは後続の要求で自動的に解決されることが期待できます。

問題が発生した場合:

何かフィードバックはありますか?

この記事を改善するための提案がある場合は、