JSS Next.js 用の Sitecoreコンテナテンプレートを元に作成した開発環境でJSSをデバッグする

samatsu 9/14/2021 857 N/A Sitecore JSS

Sitecoreはコンテナを使用したローカル開発環境のセットアップを簡素化するためにスターターテンプレートを用意しています。用意されているスターターテンプレートは、記事作成時点でASP.NET Core 開発用のものと、JSS Next.js SDK 用の2種類です。

ASP.NET Core SDKを使用するWebサイトを開発する際にプログラムをデバッグする方法については、コンテナ内で実行されているSitecoreの開発プログラムをデバッグする方法で紹介しました。

今回は、Next.js JSS SDK 用に用意されているJSSアプリのデバッグを行う方法について記載します。

今回の環境は次の通りです

Sitecore Version: 10.1-ltsc2019
node: 14.7.6
docker: 20.10.8, build 3967b7d

私がnodeについて詳しくないので用語に間違いがあるかもしれませんのでご容赦ください。

1. デバッグで使用するポートの公開設定

まず、開発用のスターターテンプレートを元に、プロジェクトをセットアップしたら、ルートフォルダー直下にある、docker-compose.override.yml を開き、 rendering コンテナの定義で、9229ポートのホスト側への公開設定を追加します。デフォルトで、nodejsは9229番ポートを使ってデバッグ接続を行います。今回はホスト側でも9229ポートで公開するように例えば次のように設定を追加します。

    ports:
      - "9229:9229"

2. デバッグ接続を受け入れる設定

Node.jsをデバッグ接続を受け入れるように実行するには --inspect オプションを指定して起動する必要があります。実は、スターターテンプレートのレンダリングホスト(rendering コンテナ)は、--inspect オプションを指定して起動するようになっています。その設定はプロジェクトフォルダーの src/rendering/package.json に記載されています。

package.json の script セクションを見ると次のようになっています。

"next:dev": "cross-env NODE_OPTIONS='--inspect' next dev",

私はこの設定の正確な意味を理解しておらず、デバッグ接続を受け入れることができる状態になっていると勘違いして大いにはまって時間を消費してしまいました。今回コンテナ内で実行されているNode.jsサーバーで実行されているNext.js JSSアプリをデバッグします。そのため、実はこれだけの設定では不十分でで、NODE_OPTIONS='--inspect=0.0.0.0:9229' というオプションを指定する必要があります。0.0.0.0:9229 の詳細は割愛しますが、これにより任意のクライアントからのデバッグ接続を受け入れることができるようになります。リモートからのデバッグ接続を受け入れるように、次のように--inspectの設定を変更しました。

"next:dev": "cross-env NODE_OPTIONS='--inspect=0.0.0.0:9229' next dev",

nodejsのデバッグに関するページを閲覧はしていたのですが、--inspectオプションを指定するだけでは不十分ということに気づかずかなり時間をロスしてしましました。

3. クライアントからデバッグ接続の設定を行う

プログラムのデバッグはVS Code や Chrome、Edge 等から行えます。今回はVS Codeを使用します。プロジェクトフォルダーの src/rendering フォルダーを VS Codeで開き、デバッグの設定を追加します。

例えば下図のように左側の列のデバッグボタンをクリックし、使用するデバッグの設定を選ぶメニューから Add Configuration を選択します。

テンプレートの一覧から、Node.js: Attach to Remote Program テンプレートを選択肢、lancuh.json に設定を追加します。

追加したひな型を変更し、例えば次のように設定を行います。今回接続に使用するポートは9229です。addressの設定は必須ですので、ローカルのマシン上で動作しているコンテナにデバッグ接続する場合はlocalhostを指定します。

    {
      "address": "localhost",
      "localRoot": "${workspaceFolder}",
      "name": "Attach to Remote",
      "port": 9229,
      "remoteRoot": "C:\\app",
      "request": "attach",
      "skipFiles": [
        "<node_internals>/**"
      ],
      "type": "pwa-node"
    },

後は、ブレイクポイントを設定した状態でデバッグを開始して、デバッグが開始されることを確認します。

スターターテンプレートからセットアップしたサイト(例:https://www.myproject.localhost/) などにアクセスし、ブレイクポイントを設定した箇所でプログラムをデバッグできることを確認します。

このとき、もしデバッグ接続ができない場合は、 docker-compose down や docker-compose stop コマンドでコンテナを削除または停止して、コンテナを再起動してください。

また、ChromeやEdgeからもデバッグできます。chrome://inspect や edge://inspect からinspectというリンクを選択するだけです。概要の手順はDebugging - Getting Started | Node.js (nodejs.org)などを参考にしてください。

詳細な手順は省きますが例えば、下図のような画面で Remote Target に表示されたNext.js を実行するコンテナ(rendering)の inspect をクリックして、表示されるポップアップ画面でローカルのNext.jsアプリのルートフォルダー(src/rendering) を指定します。

わかってしまえば大したことがないのですが、node.jsのデバッグ手順の理解に不足があり、traefikの設定なども疑ったりして、不要じゃ試行錯誤を実施した結果デバッグできるようになるまでかなり時間がかかりました。同じような状況になった方のお役に立てればと思いデバッグを有効化する方法を記載しました。

// Net planet-es V2