Multisite support for Sitecore JSS – Next.js using Vercel’s Edge Middleware – Demo on Sitecore Demo Portal (XM + Edge)!

I’ve come across the requirement for supporting a multi-site Sitecore-SXA approach with a single rendering host (Next.js app).

With this approach, we want to lower the costs by deploying to a single Vercel instance and making use of custom domains or sub-domains to resolve the sites.

If you have a look at the Sitecore Nextjs SDK and/or the starter templates, you’ll notice that there is no support for multi-site, so here I’ll go through a possible solution for this scenario where we need also to keep the SSG/ISR functionality from Next.js/Vercel.

The approach

To make it work we basically need to somehow resolve the site we’re trying to reach (from hostname or subdomain) and then pass it through the LayoutService and DictionaryService to resolve those properly.

As we’ve also enabled SSG, we’ll need to do some customization to the getStaticPaths so it generates the sitemap for each site.

Resolving the site by custom domains or subdomains

As I mentioned in the title of the post, I’ll be using Edge Middleware for that, so I’ve based this on the examples provided by Vercel, check the hostname-rewrites example!

For more details on Edge Middleware, please refer to my previous post!

Dynamic routes

Dynamic Routes are pages that allow you to add custom parameters to your URLs. So, we can then add the site name as a param to then pass it through the layout and dictionary services. For more details on dynamic routing, check the official documentation and the example here!

Demo!

We now know all the basics, let’s move forward and make the needed changes to make it work.

For demoing it, I’m just creating a new Sitecore Next.js JSS app by using the JSS initializer and the just recently released Sitecore Demo Portal! – Check this great blog from my friend Neil Killen for a deep overview of it!

Changes to the Next.js app

To accomplish this, as already mentioned, we have to play with dynamic routing, so we start by moving the [[…path]].tsh to a new folder structure under ‘pages’: pages/_sites/[site]/[[…path]].tsh

Then we’ve to create the middleware.ts file in the root of src. The code here is quite simple, we get the site name from the custom domain and then update the pathname with it to do an URL rewrite.

import { NextRequest, NextResponse } from 'next/server'
import { getHostnameDataOrDefault } from './lib/multisite/sites'

export const config = {
  matcher: ['/', '/_sites/:path'],
}

export default async function middleware(req: NextRequest): Promise<NextResponse> {
  const url = req.nextUrl.clone();
  // Get hostname (e.g. vercel.com, test.vercel.app, etc.)
  const hostname = req.headers.get('host');

  // If localhost, assign the host value manually
  // If prod, get the custom domain/subdomain value by removing the root URL
  // (in the case of "test.vercel.app", "vercel.app" is the root URL)
  const currentHost =
    //process.env.NODE_ENV === 'production' &&
    hostname?.replace(`.${process.env.ROOT_DOMAIN}`, '');
  const data = await getHostnameDataOrDefault(currentHost?.toString());

  // Prevent security issues – users should not be able to canonically access
  // the pages/sites folder and its respective contents.
  if (url.pathname.startsWith(`/_sites`)) {
    url.pathname = `/404`
  } else {
    // rewrite to the current subdomain
    url.pathname = `/_sites/${data?.subdomain}${data?.siteName}${url.pathname}`;
  }
  
  return NextResponse.rewrite(url);
}

You can see the imported function getHostnameDataOrDefault called there, so next, we add this to /lib/multisite/sites.ts

const hostnames = [
  {
      siteName: 'multisite_poc',
      description: 'multisite_poc Site',
      subdomain: '',
      rootItemId: '{8F2703C1-5B70-58C6-927B-228A67DB7550}', 
      languages: [
        'en'
      ],
      customDomain: 'www.multisite_poc_global.localhost|next12-multisite-global.vercel.app',
      // Default subdomain for Preview deployments and for local development
      defaultForPreview: true,
    },
    {
      siteName: 'multisite_poc_uk',
      description: 'multisite_poc_uk Site',
      subdomain: '',
      rootItemId: '{AD81037E-93BE-4AAC-AB08-0269D96A2B49}', 
      languages: [
        'en', 'en-GB'
      ],
      customDomain: 'www.multisite_poc_uk.localhost|next12-multisite-uk.vercel.app',
    },
]
// Returns the default site (Global)
const DEFAULT_HOST = hostnames.find((h) => h.defaultForPreview)

/**
 * Returns the data of the hostname based on its subdomain or custom domain
 * or the default host if there's no match.
 *
 * This method is used by middleware.ts
 */
export async function getHostnameDataOrDefault(
  subdomainOrCustomDomain?: string
) {
  if (!subdomainOrCustomDomain) return DEFAULT_HOST

  // check if site is a custom domain or a subdomain
  const customDomain = subdomainOrCustomDomain.includes('.')

  // fetch data from mock database using the site value as the key
  return (
    hostnames.find((item) =>
      customDomain
        ? item.customDomain.split('|').includes(subdomainOrCustomDomain)
        : item.subdomain === subdomainOrCustomDomain
    ) ?? DEFAULT_HOST
  )
}

/**
 * Returns the site data by name
 */
export async function getSiteData(site?: string) {
  return hostnames.find((item) => item.siteName === site);
}

/**
 * Returns the paths for `getStaticPaths` based on the subdomain of every
 * available hostname.
 */
export async function getSitesPaths() {
  // get all sites
  const subdomains = hostnames.filter((item) => item.siteName)

  // build paths for each of the sites
  return subdomains.map((item) => {
    return { site: item.siteName, languages: item.languages, rootItemId: item.rootItemId }
  })
}

export default hostnames

I’ve added the custom domains I’d like to use later to resolve the sites based on those. I’ve defined 2 as I want this to work both locally and then when deployed to Vercel.

Changes to the getStaticProps

We keep the code as it is in the [[…path]].tsx, you’d see that the site name is now part of the context.params (add some logging there to confirm this)

[[…path]].tsx

Changes to page-props-factory/normal-mode.ts

We need now to get the site name from the context parameters and send it back to the Layout and Dictionary services to set it out. I’ve also updated both dictionary-service-factory.ts and layout-service-factory constructors to accept the site name and set it up.

normal-mode.ts
fictionary-service-factory.ts
layout-service-factory.ts

Please note that the changes are quite simple, just sending the site name as a parameter to the factory constructors to set it up. For the dictionary, we are also setting the root item id.

Changes to getStaticPaths

We have now to modify that in order to build the sitemap for SSG taking all sites into account. The change is also quite simple:

// This function gets called at build and export time to determine
// pages for SSG ("paths", as tokenized array).
export const getStaticPaths: GetStaticPaths = async (context) => {
  ...

  if (process.env.NODE_ENV !== 'development') {
    // Note: Next.js runs export in production mode
    const sites = (await getSitesPaths()) as unknown as Site[];
    const pages = await sitemapFetcher.fetch(sites, context);
    const paths = pages.map((page) => ({
      params: { site: page.params.site, path: page.params.path },
      locale: page.locale,
    }));

    return {
      paths,
      fallback: process.env.EXPORT_MODE ? false : 'blocking',
    };
  }

  return {
    paths: [],
    fallback: 'blocking',
  };
};

As you can see, we are modifying the fetcher and sending the site’s data as an array to it so it can process all of them. Please note the site param is now mandatory so needs to be returned in the paths data.

Custom StaticPath type

I’ve defined two new types I’ll be using here, StaticPathExt and Site

Site.ts
StaticPathExt.ts

We need to make some quick changes to the sitemap-fetcher-index.ts now, basically to send back to the plugin the Sites info array and to return the new StaticPathExt type.

import { GetStaticPathsContext } from 'next';
import * as plugins from 'temp/sitemap-fetcher-plugins';
import { StaticPathExt } from 'lib/type/StaticPathExt';
import Site from 'lib/type/Site';

export interface SitemapFetcherPlugin {
  /**
   * A function which will be called during page props generation
   */
  exec(sites?: Site[], context?: GetStaticPathsContext): Promise<StaticPathExt[]>;
}

export class SitecoreSitemapFetcher {
  /**
   * Generates SitecoreSitemap for given mode (Export / Disconnected Export / SSG)
   * @param {GetStaticPathsContext} context
   */
  async fetch(sites: Site[], context?: GetStaticPathsContext): Promise<StaticPathExt[]> {
    const pluginsList = Object.values(plugins) as SitemapFetcherPlugin[];
    const pluginsResults = await Promise.all(
      pluginsList.map((plugin) => plugin.exec(sites, context))
    );
    const results = pluginsResults.reduce((acc, cur) => [...acc, ...cur], []);
    return results;
  }
}

export const sitemapFetcher = new SitecoreSitemapFetcher();

And last, we update the graphql-sitemap-service.ts to fetch all sites and add its info to get returned back to the getStaticPaths

async exec(sites: Site[], _context?: GetStaticPathsContext): Promise<StaticPathExt[]> {
    let paths = new Array<StaticPathExt>();
    for (let i = 0; i < sites?.length; i++) {
      const site = sites[i]?.site || config.jssAppName;
      this._graphqlSitemapService.options.siteName = site;
      this._graphqlSitemapService.options.rootItemId = sites[i].rootItemId;
      if (process.env.EXPORT_MODE) {
        // Disconnected Export mode
        if (process.env.JSS_MODE !== 'disconnected') {
          const p = (await this._graphqlSitemapService.fetchExportSitemap(
            pkg.config.language
          )) as StaticPathExt[];
          paths = paths.concat(
            p.map((page) => ({
              params: { path: page.params.path, site: site },
              locale: page.locale,
            }))
          );
        }
      }
      const p = (await this._graphqlSitemapService.fetchSSGSitemap(
        sites[i].languages || []
      )) as StaticPathExt[];
      paths = paths.concat(
        p.map((page) => ({
          params: { path: page.params.path, site: site },
          locale: page.locale,
        }))
      );
    }
    return paths;
  }

We’re all set up now! Let’s now create some sample sites to test it out. As I already mentioned, I’m not spinning up any Sitecore instance locally or Docker containers but just using the new Demo Portal, so I’ve created a demo project using the empty template (XM + Edge). This is really awesome, I haven’t had to spend time with this part.

Sitecore Demo Portal

I’ve my instance up and running, and it comes with SXA installed by default! Nice ;). So, I’ve just created two sites under the same tenant and added some simple components (from the JSS boilerplate example site).

Sitecore Demo Portal instance

From the portal, I can also get the Experience Edge endpoint and key:

Sitecore Demo Portal

Note: I’ve had just one thing to do and I’ll give feedback back to Sitecore on this, by default there is no publishing target for Experience Edge, even though it comes by default on the template, so I’ve to check the database name used in XM (it was just experienceedge) and then created a new publishing target.

The first thing is to check the layout service response gonna work as expected, so checked the GraphQL query to both XM and Experience Edge endpoints to make sure the sites were properly resolved.

From XM: https://%5Bsitecore-demo-instance%5D/sitecore/api/graph/edge/ui

GraphQL playground from XM

From Experience Edge: https://edge-beta.sitecorecloud.io/api/graphql/ide

GraphQL playground from Experience Edge

All good, also checked that the site ‘multisite_poc_uk‘ is also working fine.

Now, with everything set, we can test this out locally. The first thing is to set the environment variables so those point to our Experience Edge instance.

  • JSS_EDITING_SECRET: (from Demo Portal)
  • SITECORE_API_KEY: (from Demo Portal)
  • SITECORE_API_HOST=https://edge-beta.sitecorecloud.io
  • GRAPH_QL_ENDPOINT=https://edge-beta.sitecorecloud.io/api/graphql/v1
  • FETCH_WITH=GraphQL

Let’s run npm run start:connected in our src/rendering folder!

Note: I’ve added hosts entries to test this out locally:

127.0.0.1 www.multisite_poc_global.localhost
127.0.0.1 www.multisite_poc_uk.localhost
npm run start:connected

If everything went well, you should be able to see that (check the logging we added in the getStaticProps previously).

UK Site
Global Site

Cool! both sites are properly resolved and the small change I’ve made to the content bock text confirms that.

Let’s now run npm run next:build so we test the SSG:

npm run next:build

Deploying to Vercel

We’re all set to get this deployed and tested in Vercel, exciting!

I won’t go through the details on how to deploy to Vercel as I’ve already written a post about it, so for details please visit this post!

Couple of things to take into account:

  • I don’t push my .env file to the GitHub repo, so I’ve set all the environment variables in Vercel itself.
  • I’ve created 2 new custom domains to test this. Doing that is really straightforward, in Vercel got to the project settings, and domains and create those:
Vercel custom domains

I’ve pushed the changes to my GitHub repo that is configured in Vercel so a deployment just got triggered, check build/deployment logs and the output!

Looking good! let’s try out the custom domains now:

https://next12-multisite-global.vercel.app/

Global site

https://next12-multisite-uk.vercel.app/

UK site

I hope you find it interesting, you can find the code I’ve used for this example in this GitHub repo.

If you have a better or different approach to resolve multisite within a single Next.js app, please comment! I’d love to hear about other options.

I’d like also to say thanks to Sitecore for this Portal Demo initiative, it’s really helpful to speed up PoC and demos to customers!

Thanks for reading!

Start your commerce solution in minutes with Vercel, Next.js Commerce template, and the new Sitecore OrderCloud® integration – Part II

In my previous post, I’ve shared how easy is to get your Next.js Commerce solution up and running powered by Sitecore OrderCloud®. Please have a look at the previous post before getting into this reading as this is a continuation that focuses on the development environment, the local solution setup, and the CI/CD approach.

Local solution setup

Let’s get back to our Github repo and clone it locally, then open it on Visual Studio Code.

Starter kit solution on VS Code

We have our solution cloned locally, let’s open a terminal now and run npm install to install all dependency packages needed by the solution.

npm i

Vercel CLI

The Vercel’s command-line interface enables instant cloud deployment and local development.
To learn more, visit the official documentation, let’s get started now by installing the CLI:

npm i -g vercel

Now we can just run “vercel link” to link our local repo with the Vercel project.

Use your Vercel credentials to login, choose your scope, and Vercel will magically recommend the proper project to link to. Veryfi all this information and proceed, if everything went good, you should see a green tick saying your project is now linked.

vercel link

Now we need to get in our local all the environment variables we got created on Vercel:

Environment Variables needed for communicating with the Sitecore OrderCloud API

We can speed up the process of creating those variables locally by using the Vercel CLI command “vercel env pull

You can see now that a new .env file got created and contains all the variables we need:

environment variables locally imported

Also, the previous step created the “vercel” folder where we can find the project.json configuration file.

Let’s test it out!

We got now everything in place, so let’s just run the app locally in develop mode by running “npm run dev

npm run dev

Pum! Another unexpected exception 😦

After some analysis, I noticed there is an issue in this file (packages/commerce/src/config.cgs), while trying to build the path to the next.config file under packages:

const commerceNextConfig = importCwd(path.join(provider, 'next.config'))

I just updated with the hardcoded path and it seemed to fix the issue. Check this open issue for more details, or you can also refer to this PR that seems to be fixing the issue.

Build succeed this time 😉
Storefront site at localhost

The app is now running locally in development mode and connected to Sitecore OrderCloud.

Let’s test our CI/CD

Let’s make a quick change on our project, test it locally, push it to Github and then deploy to Vercel.

So, in order to make some changes to the homepage, open and edit the pages/index.tsx file:

As you can see, I’m moving the marquee before the grid, and adding a heading text (note that you’d need to first add the import):

Here we go! As we’re running the app on development mode, we get feedback instantly, so get back to the local site in the browser and refresh it:

The marquee is now at the top and right after the heading text we added (“Sitecore OrderCloud Rocks!“).

Cool, so now that we’re fine with our local test, we commit and push to the repo…

Just verify we pushed the changes to Github

Go back to the Vercel portal and check that the build got automatically triggered 🙂

Amazing, isn’t it? Our changes are now deployed and pushed live to Vercel:

That’s it! The main reason behind this post was to show how easy is to get started with Sitecore OrderCloud, Next.js Commerce Templates, and Vercel. The starter kit gives you everything to start working with and for start learning this new technology stack as well. So don’t waste time and go try out this by yourself!

I hope you found it interesting, and see you soon with more Sitecore related stuff!

Start your commerce solution in minutes with Vercel, Next.js Commerce template, and the new Sitecore OrderCloud® integration – Part I

In this post, I’ll describe the steps to get a full development environment from scratch, using the Next.js Commerce template integrated with OrderCloud and deploying to Vercel.

Sitecore OrderCloud®

Sitecore OrderClooud is an API-First, headless cloud platform for B2B, B2C, and B2X commerce solutions. It powers custom e-commerce experiences, order management, and B2B marketplace applications for some of the world’s most well-known brands.

If you don’t have your account yet, go here and create one, you can sign up for free!

Vercel – Next.js Commerce

Next.js Commerce is an all-in-one React starter kit for high-performance e-commerce sites. You can clone, deploy, and fully customize with a few clicks.

And again, if you don’t have an account yet, go here and create one, you can sign up for free!

If you want to learn more about Next.js, don’t hesitate to go through the official documentation, it’s really good and useful.

Let’s go and get it done!

The first step is to login into Vercel and start a new project, then we just need to choose the Next.js Commerce template:

The Vercel templates

After we choose the Next.js Commerce template, we give the Git repo a name, and click on create:

Creating the starter kit Github repo

You can now go and check what Vercel has created for you in the Github repo:

Github

If you have experience developing Next.js apps, this repo would look familiar to you.

If you look at the readme file, you will see there is a demo site powered by Sitecore OrderCloud®!

Let’s get back and continue with our setup!

We have our Github repo, let’s skip the add integrations step for now and go straight to the deploy:

Build/deploy running for the first time…
The project got deployed to Vercel

Yas! your project got built and deployed to Vercel, you can now go and browse it (amazing isn’t it?)

The Commerce site is already up and running!

Setting up the Sitecore OrderCloud® integration

The site you’re browsing now already has some content, but as we are not integrating with any e-commerce platform yet, is just statically stored and generated. Let’s change that and switch our e-commerce solution to be powered by Sitecore OrderCloud®.

For doing that, go back to your Vercel project and then go to the Settings section, then click on Integrations and search for the OrderCloud by browsing the Marketplace

Browsing the integrations Marketplace

You would now see the Sitecore OrderCloud integration under the Commerce section:

SitecoreOrderCloud integration

Then click on Add Integration and choose your Personal Account as Vercel Scope. Click on continue and then select the project we just created for the OrderCloud integration.

Add the integration and then login to your Sitecore OrderCloud account.

In the next step, you’re prompted to choose your OrderCloud Marketplace. You would see that you can choose an existing one, but this time I want to create a new one “Seed new Marketplace (ID: “NEW”)

You can see the progress and logs, yeah Vercel is creating everything on OrderCloud for you!

Get back now to your Vercel project, settings and check the Environment Variables. You can see the key values created in the previous step:

Check your Sitecore OrderCloud® Marketplace

Now, login to Sitecore OrderCloud, go to Marketplaces and you should be now able to see the newly created “Vercel Commerce

Let’s try this out. Go to the API Console and then select “Catalogs“, click on send to make the API call, and check the results:

Copy the ID (solitary-storefront) so you can now browse categories by this Catalog ID:

Let’s browse the products now, copy the category ID (shirts) and make the request from the Products section:

Time to deploy it!

We just checked that the data is created on OrderCloud and we can easily query the API to get the results. Our Vercel integration is ready and now is time to deploy it so get our app consuming OrderCloud data.

just get back to your Vercel project, go to the deployments section, select the latest green one and redeploy it:

Uuuups! the build failed this time… That’s weird and unexpected, but let’s check logs and see what’s going on:

As I mentioned in the previous step, the OrderCloud integration created the environment variables to make the app communicate with OrderCloud.

Ok, that’s odd, it seems the “COMMERCE_PROVIDER” variable is not set properly. Let’s follow the logs recommendations and update it from “ordercloud” to “@vercel/commerce-ordercloud“. Save it and redeploy:

Yas! it seems to be good now, and the build is going good, you can also see in the logs how the site is being statically generated but making requests to the OrderCloud API this time:

You can see now our site getting data from OrderCloud!

Let’s make a quick update on OrderCloud and check changes in our storefront.

Let’s make an update on the Black Hat product. For that, go to the “Products” search for the “Black Hat” and then choose “PUT Create or update a product“. Change the price from 80 to 40, and the name to “OrderCloud Black Hat“:

We can query again to make sure the price got updated:

Get back to the site and check the updated product:

We have now our e-commerce solution deployed to Vercel, powered by Sitecore OrderCloud, and our Next.js app created on our Github repo.

In the next post, I’ll be exploring and sharing the local solution setup and the CI/CD so you can get an idea of how easy is to start building your solution with this tech stack.

I hope you found this post useful!

If you are interested in this topic, please don’t hesitate to watch the full demo example from Rob Earlam on YouTube.