開発環境の作成

このドキュメントでは、XM Cloud を対象とした Web サイトの開発を行う場合の環境について紹介をします。ローカルでの Docker での環境について、XM Cloud のインスタンスに接続して開発をする方法のそれぞれの環境の整え方を紹介します。

Starter Kit の構成

Sitecore XM Cloud のプロジェクトに関する Starter Kit を GitHub のリポジトリで公開をしています。

XM Cloud Front End Application Starter Kits This repository contains the Next.js Starter Kit, and the SPA Starters monorepo (which includes a Node Proxy Application and and SPA starter apps) for Sitecore XM Cloud Development. It is intended to get developers up and running quickly with a new front end project that is integrated with Sitecore XM Cloud.

上記のリポジトリは XM Cloud のプロジェクト作成の際に選択することが可能となっています。また先にプロジェクトを作成して展開することができるように、 Use this template から新しいリポジトリを作成して、利用することも可能です。

このプロジェクトには、以下の役割のファイルが配置されています。

ディレクトリheadapps
- ディレクトリnextjs-starter/ Nest.js starter kit
  - …
- ディレクトリspa-starters/ angular starter kit
  - …
ディレクトリlocal-containers
- ディレクトリdocker
  - ディレクトリbuild/ docker build image
    …
  - ディレクトリdata/ docker data folder
    …
  - ディレクトリdeploy
    ディレクトリplatform/
    …
  - ディレクトリtraefik/ traefik data and certification
    …
  - clean.ps1 docker image clean up script
- ディレクトリscripts
  - down.ps1 docker script
  - init.ps1 init script for local instance
  - up.ps1 start xm cloud instance
- docker-compose.override.yml
- docker-compose.yml
sitecore.json Sitecore CLI configuration file
xmcloud.build.json XM Cloud Deploy configuration file

このドキュメントサイトで紹介をするテンプレートは以下のサイトになります。

Tailwind CSS Starter Kit

このプロジェクトには、 headapps/tailwind-starter のプロジェクトが追加されており、Next.js + Tailwind CSS が利用できるようにカスタマイズをしています。

どちらのプロジェクトも Docker および XM Cloud を利用した開発環境を作ることができます。今回はそれぞれの環境の準備について紹介をしていきます。

Docker の利用

Sitecore XM Cloud の開発環境をローカルの PC で利用するための仕組みとして Docker を利用して環境を用意することが出来ます。今回はこの手順を紹介します。

前提条件

今回の記事は以下の環境で実行しています。

Windows 11 Pro 23H2
Docker 4.37.0
Visual Studio Code
Google Chrome, Microsoft Edge などモダンブラウザ

Docker 環境で起動する

今回はすでにプロジェクトが出来上がっていることを想定します。プロジェクトの作成に関しては、[テンプレートの作成] (/xmcdeveloper/create-template/) で紹介をしています。Docker に関する環境は、すべて local-containers のディレクトリ配下で用意されています。

以下の手順で起動してください。

Docker Desktop が起動しているのを確認します。
管理者権限を利用できるターミナルを起動します。
対象となるフォルダに移動をして、初期化のスクリプトを実行します。この際、ライセンスファイルを指定する必要があります。
Terminal window
```
cd local-containers
./scripts/init.ps1 -InitEnv -LicenseXmlPath "C:\license\license.xml" -AdminPassword "DesiredAdminPassword"
```
Sitecore の CMS を初期化してローカルで起動するために、以下のコマンドを実行します。
Terminal window
```
.\scripts\up.ps1
```
初回の起動の際には、コンテナのイメージのダウンロードなども実行します。
途中、XM Cloud へのログイン画面が表示されます。Confirm をクリックして、ログインを完了する必要があります。
しばらくすると、XM Cloud の Docker 版の管理画面が表示されます。

これで、例えば headapps\nextjs-starter にある Next.js のプロジェクトを利用して開発をすれば、Experience Editor のレンダリングとして利用することになるため、開発環境が手元に用意できる形となります。

Docker 環境と Pages

Pages は Sitecore XM Cloud が提供する非常に便利なみたまま編集ツールであり、またパーシャルデザインの作成などの際にも利用することが可能です。同様の作業は Experience Editor でも可能ですが、XM Cloud が提供する Components との連携は Experience Editor ではできないため、基本的には Pages での作業が理想的です。

実際に、Docker 版にも Pages のアイコンが表示されています。

Launchpad

Pages をローカルで起動している Docker の環境と連携させることが可能となっています。手順としては、以下のページで公式の情報として掲載しています。

Connect XM Cloud Pages to your local XM instance When you use Docker for full-stack development in XM Cloud, and after you set up your local XM Cloud development environment, XM Cloud Pages is not connected to your locally running XM instance.

上記の手順通りに作業をすれば接続できますが、もっと簡単に接続することができるブラウザの機能拡張が提供されています。

Sitecore XM Cloud Extensions Browser extension that improves Sitecore XM Cloud user experience.

この機能拡張をインストールすれば、Pages をローカルのインスタンスに簡単に接続することができます。下記の手順は機能拡張をインストール後の手順となります。

ローカルの管理画面にある Pages のアイコンを利用して起動します
機能拡張を起動して、ローカルのインスタンスの URL を入れます
URL を設定すると以下のようにローカルのインスタンスに接続されます
ローカルの環境が反映されているか確認をするために、以下のようにアイテムを変更します。
Pages を更新すると、ローカルのコンテンツを読み込んで表示していることを確認できました。

Docker を利用して開発をする環境がこれで準備ができた形です。Docker の環境は誰にも影響を与えることなく、手元の開発環境を利用できるという点では非常に強力です。

XM Cloud インスタンス

Docker とは異なり、SaaS の環境として提供されている XM Cloud を開発用サーバーとして利用することも可能です。ここでは、すでに XM Cloud に展開をしている環境を利用して、手元の開発環境と連携する方法を紹介します。

前提条件

CMS のサーバーとしてはクラウド上のインスタンスを利用しながら、ローカルで動作する Next.js のプロジェクトと繋げて動作させる形となります。このため、Next.js が動作できれば、問題なく作業をすることが可能です。前提条件は以下の通りです。

Sitecore XM CLoud の開発用インスタンス
Sitecore JSS 21.6 以降
Node 22.x 以上
Visual Studio Code
Google Chrome, Microsoft Edge などモダンブラウザ

今回は、macOS の環境で Next.js のプロジェクトを起動して、インターネット上にある開発サーバーと連携させる環境を確認していきます。

環境の構築

まず最初に、ローカルで Next.js が動作する環境を用意する必要があります。手順は以下の通りです。

XM Cloud Deploy で対象となるインスタンスの、Developer Settings にアクセスをします
対象となる Site を選択して、Environment variables の値を確認します。

ローカルで起動する Next.js のフォルダに .env.local ファイルを作成します。

SITECORE_EDGE_CONTEXT_ID=contect-id-preview
SITECORE_SITE_NAME=nextjs-starter
JSS_EDITING_SECRET=editing-secret

ローカルで起動しますが、いつもと異なり start:connected を利用します。
Terminal window
```
npm install
npm run start:connected
```

これでローカルの Next.js のプロジェクトが Sitecore に接続をしてローカルで表示されるようになりました。

Basic site

続いて Pages を今回立ち上げたローカルのプロジェクトと接続をします。

XM Cloud で Pages を開きます
みたまま編集をするための画面にある Default editing host の項目をクリックして、Localhost を選択、http://localhost:3000 を設定します。
設定をすると、You are working with a local host. というメッセージを表示しながら、ローカルの Next.js につながっている状況を確認することができます。
ローカルで起動している Next.js のログを確認すると、Pages がローカルのインスタンスを利用していることを確認することができました。

このように、XM Cloud のサーバーインスタンスを利用して、ローカルの Next.js などのプロジェクトの開発をすることができます。

まとめ

今回は Docker を利用してローカルで動作する XM Cloud を利用する場合に、Pages を利用できる手順を紹介しました。合わせて、ローカルで起動している Next.js のプロジェクトを SaaS で展開している XM Cloud に接続して、また Pages をローカルの Next.js につなげるような形としました。

XM Cloud のサーバーを開発者人数分用意するのは大変なので Docker の環境を活用する、という形で２つのパターンを上手に活用してください。