For some projects, it can be challenging to migrate from Sitecore XP to XM Cloud seamlessly, as not everything is compatible. However, when we develop new features for Sitecore XP, we try to take into account that they should be compatible with XM Cloud. One of our clients wants a new website within their existing Sitecore XP project. We are developing this website using Next.js and aim to keep it XM Cloud compatible. We achieve this by regularly testing the website on XM Cloud and addressing common challenges along the way. In the following steps, we discuss how to overcome these challenges and ensure compatibility with XM Cloud:

1. Set up XM Cloud locally by creating a new GitHub repository using the following template: https://github.com/sitecorelabs/xmcloud-foundation-head. If everything is set up correctly through .\init.ps1, you should be able to run XM Cloud local in Docker by executing .\up.ps1.

2. Make a copy of the Next.js project that uses Sitecore XP so you can adjust values for XM Cloud.

3. Export all Sitecore items. We have exported the following items from Sitecore XP through a package and then imported them into XM Cloud:

   • Templates
   • Renderings
   • Placeholder settings
   • Layouts
   • Settings
   • API keys
   • Content

4. Update the scjssconfig.json file in the copy of the Next.js project. Make sure to adjust the instancePath and layoutServiceHost to point to XM Cloud.

For example:

{
  "sitecore": {
    "instancePath": "C:\\inetpub\\wwwroot\\xm-cloud-experiment-edge\\src\\nextjs-app",
    "apiKey": "",
    "deploySecret": "",
    "deployUrl": "",
    "layoutServiceHost": "https://xmcloudcm.localhost"
  }
}

5. As the next step, we need to adjust our config using a patch. We have to add a site to our sites XML. We are running XM Cloud in Docker and can't simply copy our config file like we did with Sitecore XP. Instead, you need to place your config file in the following folder: ClonedfolderPath\docker\deploy\platform\. Docker will then pick up and apply the files. This is my full path for the config file: C:\inetpub\wwwroot\xm-cloud-experiment-edge\docker\deploy\platform\App_Config\Include\Sites.config. It is important to use database="master" since there is no web database in XM Cloud.

This is the Sites.config file:

<?xml version="1.0" encoding="utf-8" ?>

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" xmlns:set="http://www.sitecore.net/xmlconfig/set/" xmlns:role="http://www.sitecore.net/xmlconfig/role/" xmlns:env="http://www.sitecore.net/xmlconfig/env/">
    <sitecore>
        <sites>
            <site name="werkenbij"
                  inherits="website"
                  language="nl-NL"
                  contentLanguage="nl-NL"
                  scheme="https"
                  rootPath="/sitecore/content/WerkenBij"
                  dictionaryPath="/sitecore/content/WerkenBij/Dictionary"
                  dictionaryCacheSize="100MB"
                  dictionaryCacheLifetime="86400"
                  startItem="/Home"
                  cacheHtml="false"
                  hostName="xmcloudcm.localhost"
                  targetHostName="xmcloudcm.localhost"
                  database="master" />
        </sites>
    </sitecore>

</configuration>

6. Now that we have imported the content and added our site, we can try to retrieve the content via GraphQL. XM Cloud already has the following endpoint available locally: /sitecore/api/graph/edge. To open the GraphQL Playground, you need to add /ide to this URL. This is my local URL: https://xmcloudcm.localhost/sitecore/api/graph/edge/ide.

If everything goes well, you should see this:

7. It's time to connect the Next.js app to the GraphQL environment we just tested. Start by updating the graphQLEndpointPath to /sitecore/api/graph/edge in the package.json file in the copy of the Next.js project. Then, I added process.env['NODE_TLS_REJECT_UNAUTHORIZED'] = "0"; to /scripts/fetch-graphql-introspection-data.ts. This is needed to ensure that this copy of the Next.js project can connect locally to the XM Cloud test environment I have running.

8. To ensure that GraphQL has query types, you can execute npm run graphql:update and npm run bootstrap. You might encounter an out of memory error because Sitecore registers too many types by default. The solution is to write an additional patch config that limits this. This file can be placed in the same location as the Sites.config file.

This is the GraphQL.config file:

<?xml version="1.0" encoding="utf-8" ?>

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" xmlns:role="http://www.sitecore.net/xmlconfig/role/">
    <sitecore>
        <api>
            <GraphQL>
                <!-- the defaults section contains config templates that can be reused elsewhere using 'ref' -->
                <defaults>
                    <content>
                        <schemaProviders>
                            <edgeContent type="Sitecore.Services.GraphQL.EdgeSchema.EdgeSchemaProvider, Sitecore.Services.GraphQL.EdgeSchema">
                                <templates type="Sitecore.Services.GraphQL.Content.TemplateGeneration.Filters.StandardTemplatePredicate, Sitecore.Services.GraphQL.Content">
                                    <database>$(1)</database>
                                    <!-- Only include our JSS application -->
                                    <paths hint="list:AddIncludedPath">
                                        <foundation>
                                            <patch:delete />
                                        </foundation>
                                        <feature>
                                            <patch:delete />
                                        </feature>
                                        <project>
                                            <patch:delete />
                                        </project>
                                        <userdefined>
                                            <patch:delete />
                                        </userdefined>
                                        <jssSite>/sitecore/templates/Project/WerkenBij</jssSite>
                                    </paths>                 
                                </templates>
                             </edgeContent>
                        </schemaProviders>
                    </content>
                </defaults>
            </GraphQL>
        </api>
         </sitecore>
</configuration>

You can find more information about the issue here:
'jss bootstrap' causes JavaScript heap out of memory error on graphql-let step
Applying patch config files to a local XM Cloud Docker environment

9. If the above scripts no longer give an error, all you need to do is run npm run next:build and then npm run next:start. If everything goes well, you should see the website, and the content will be coming from XM Cloud.

By following these steps, you can ensure that your Next.js project is compatible with XM Cloud and that you can test and develop your website locally while leveraging the XM Cloud infrastructure.

Keep in mind that migrating from Sitecore XP to XM Cloud can still present challenges, especially when dealing with incompatible features or components. Always test your website thoroughly on XM Cloud to ensure everything works as expected.

In conclusion, using Next.js in combination with XM Cloud offers an excellent opportunity to build modern and scalable websites. By following best practices and regularly testing compatibility, you can ensure a seamless transition from Sitecore XP to XM Cloud for your projects.