DEV Community: Juan Gutierrez

Enhancing Multisite and Market-Specific Handling with Sitecore JSS and Next.js

Juan Gutierrez — Fri, 04 Oct 2024 10:47:14 +0000

When building a multisite, multilingual website with Sitecore JSS and Next.js, efficiently managing market-specific content for both editors and users presents unique challenges. While Sitecore provides powerful features for handling multiple languages and sites out of the box, extending these capabilities for a multi-market setup requires custom implementation to ensure a seamless experience.

In this blog, we’ll explore how Sitecore’s default multisite and multilingual handling works, and how we built on top of it to meet Uniworld's market-specific requirements. We'll cover the key plugins and configurations we modified, and the rationale behind each change.

Default Sitecore Multisite and Language Handling

Sitecore's Next.js Multisite Add-on includes a rich set of features designed to simplify multisite and multilingual setups:

Multisite Middleware: Rewrites requests to the correct site based on the incoming hostname.
Site Resolver: Uses GraphQL to fetch site information at build time, including site-specific settings like default language.
Internationalized Routing: Uses Next.js i18n to manage different languages based on the request path, with fallbacks to default settings when necessary.
By default, Sitecore handles language and site-specific routing using a pattern like /site/. This ensures that content is appropriately scoped across different sites hosted under the same Next.js instance.

Sitecore Default Language Behavior

In the default setup, Sitecore and Next.js use the hostname and URL path to determine which site and language to serve. If a language prefix is available in the URL (e.g., /en-us), Sitecore serves content in that language. If the language is not specified, it uses the default language for the given site.

However, this default behavior does not seamlessly accommodate market-specific redirections, requiring customizations to handle:

Serving market-specific content based on the user's country or preferences.
Supporting the Experience Editor and Preview without conflicts.
Integrating market handling into the multisite setup.

Challenges in Multisite and Market Handling

We faced a few challenges while creating a multi-market solution:

Serving Correct Content by Market: Ensuring the correct market was targeted based on the user's location or preferences.
Experience Editor Compatibility: Ensuring that editors could preview and edit content without inappropriate redirections.
Scalable Multisite Integration: Seamlessly integrating market-specific handling with Sitecore’s multisite capabilities.

Mapping Languages and Markets

Our goal was to create a multi-market experience that delivers localized content tailored to users' geographic locations or preferences. Here is how we mapped markets and corresponding locales:

Asia-Pacific (AP): en-PH for English spoken in Asia.
Australia (AU): en-AU.
Canada (CA): en-CA.
European Union (EU): en-IE.
New Zealand (NZ): en-NZ.
United Kingdom (UK): en-GB.
United States (US): en-US.
South Africa (ZA): en-ZA.

The objective was to ensure that users from these markets receive localized content for their specific market, and we wanted to handle this efficiently at the middleware level using Next.js.

Custom Implementation: Steps Taken

To meet these requirements, we introduced several key changes in Next.js middleware and configuration, as well as Sitecore plugins. Here is a detailed breakdown of the updates.

1. Market Plugin for Middleware

The Market Plugin addresses market-specific content handling by leveraging middleware in Next.js. It ensures users are redirected to the appropriate market URL, with proper locale detection and handling.

class marketPlugin implements MiddlewarePlugin {
  order = 0;

  constructor() {
    console.log('[marketPlugin] Initializing marketPlugin...');
  }
  async exec(req: NextRequest, res?: NextResponse): Promise {
    const { pathname } = req.nextUrl;

    // Exclude assets and other unnecessary routes
    if (this.excludeRoute(pathname)) {
      console.log([marketPlugin] Skipping route: ${pathname});
      return res || NextResponse.next();
    }

    console.log([marketPlugin] Executing marketPlugin for request: ${req.url});

    const cookieLocale = req.cookies.get('NEXT_LOCALE');
    const country = req.geo?.country?.toLowerCase() || 'us';

    let market: string;
    let locale: string;

    const urlmarket = pathname.split('/')[1];

    if (validmarkets.includes(urlmarket)) {
      console.log([marketPlugin] URL market detected: ${urlmarket});
      market = urlmarket;
    } else if (cookieLocale) {
      console.log([marketPlugin] Locale cookie found: ${cookieLocale.value});
      market = localeTomarketMap[cookieLocale.value.toLowerCase()] || 'us';
    } else {
      console.log([marketPlugin] No valid market found, using country: ${country});
      market = determinemarketFromCountry(country);
    }

    locale = determineLanguageFrommarket(market);
    console.log([marketPlugin] Determined locale from market: ${locale});

    if (cookieLocale?.value !== locale) {
      console.log([marketPlugin] Setting locale cookie to: ${locale});
      res = res || NextResponse.next();
      res.cookies.set('NEXT_LOCALE', locale, {
        path: '/',
        maxAge: 60 * 60 * 24 * 30, // 30 days
      });
    }

    if (!pathname.startsWith(/${market})) {
      const newUrl = req.nextUrl.clone();
      newUrl.pathname = /${market}${pathname === '/' ? '' : pathname};
      console.log([marketPlugin] Redirecting to market-specific path: ${newUrl});
      res = NextResponse.redirect(newUrl);
    }

    console.log([marketPlugin] Finished marketPlugin execution for request: ${req.url});
    return res || NextResponse.next();
  }

  private excludeRoute(pathname: string): boolean {
    const isExcluded =
      pathname.includes('.') || // Skip files (e.g., .css, .js, .png)
      pathname.startsWith('/api/') || // Skip Next.js API routes
      pathname.startsWith('/sitecore/'); // Skip Sitecore API routes

    console.log([marketPlugin] Checking if route should be excluded: ${pathname} - Excluded: ${isExcluded});
    return isExcluded;
  }
}
export const marketPlugin = new marketPlugin();

Why We Modified It:
Path Detection and Exclusion: The excludeRoute function was implemented to skip unnecessary routes like assets, API requests, and Sitecore service requests.
Market Detection: The plugin first checks if a valid market prefix exists in the URL. If not, it attempts to use a cookie (NEXT_LOCALE) to determine the market. If the cookie is unavailable, it falls back to the country code from the request geo headers.
Setting Cookies and Redirects: If the market in the URL does not match the detected or preferred market, the user is redirected to the appropriate market path, and the locale cookie is set for consistent behavior.

2. Updated next.config.js for Market and Locale Management

const jssConfig = require('./src/temp/config');

module.exports = {
  i18n: {
    locales: [
      'en', 'en-PH', 'en-AU', 'en-CA', 'en-IE', 'en-NZ', 'en-ZA', 'en-GB', 'en-US',
    ],
    defaultLocale: jssConfig.defaultLanguage,
    localeDetection: false, // Disabled locale detection since we handle it through middleware
  },
};

Why We Modified It:
We disabled automatic locale detection (localeDetection: false) because our custom middleware handled the logic for determining the correct locale and market. This allowed us more granular control over which market a user should see.

3. Update to page-props.ts to Include Market

To support the new changes, the SitecorePageProps interface was updated to include the market property.

export type SitecorePageProps = {
  site: SiteInfo;
  locale: string;
  dictionary: DictionaryPhrases;
  componentProps: ComponentPropsCollection;
  notFound: boolean;
  layoutData: LayoutServiceData;
  headLinks: HTMLLink[];
  market: string; // New property for storing market information
};

Key Changes:
Market Property: Added market to store the market context for each request.

4. Updated Page Props Factory Plugin

class SitePlugin implements Plugin {
  order = 0;
  async exec(props: SitecorePageProps, context: GetServerSidePropsContext | GetStaticPropsContext) {
    if (context.preview) {
      console.log('[SitePlugin] Preview mode detected. Skipping site resolution.');
      return props;
    }
    const path = this.getNormalizedPath(context);
    console.log([SitePlugin] Resolving site for path: ${path});

    const siteData = getSiteRewriteData(path, config.sitecoreSiteName);
    console.log([SitePlugin] Site data extracted from path:, siteData);

    const market = this.getmarketFromParams(context);
    const locale = determineLanguageFrommarket(market);

    context.locale = locale;
    props.site = siteResolver.getByName(siteData.siteName);
    props.locale = locale;
    props.market = market;
    console.log([SitePlugin] Props:, props);
    console.log([SitePlugin] Context:, context);

    return props;
  }

  private getmarketFromParams(context?: GetServerSidePropsContext | GetStaticPropsContext): string {
    if (context?.params && Array.isArray(context.params.path) && context.params.path.length > 1) {
      const [, secondSegment] = context.params.path;
      if (validmarkets.includes(secondSegment)) {
        context.params.path.splice(1, 1);
        return secondSegment;
      }
    }
    return '';
  }

  private getNormalizedPath(context: GetServerSidePropsContext | GetStaticPropsContext): string {
    if (!context.params) return '/';
    return Array.isArray(context.params.path) ? context.params.path.join('/') : context.params.path ?? '/';
  }
}
export const sitePlugin = new SitePlugin();

Why We Modified It:
The SitePlugin helps resolve the current site context based on the request, and modifications were made to include both market and locale. This ensures that the rest of the page-building process is aware of the market-specific context.

Key Changes:
Market and Locale Handling: The SitePlugin was updated to extract market information from the URL and set it within the context, ensuring consistency across the rendering process.

5. Preview Mode Plugin Updates

import { GetServerSidePropsContext, GetStaticPropsContext } from 'next';
import {
  SiteInfo,
  personalizeLayout,
  getGroomedVariantIds,
} from '@sitecore-jss/sitecore-jss-nextjs';
import {
  editingDataService,
  isEditingMetadataPreviewData,
} from '@sitecore-jss/sitecore-jss-nextjs/editing';
import { SitecorePageProps } from 'lib/page-props';
import { graphQLEditingService } from 'lib/graphql-editing-service';
import { Plugin } from '..';
import { determinemarketFromLocale } from 'lib/helpers/marketHelper';

class PreviewModePlugin implements Plugin {
  order = 1;

  async exec(props: SitecorePageProps, context: GetServerSidePropsContext | GetStaticPropsContext) {
    if (!context.preview) {
      console.log('[PreviewModePlugin] Not in preview mode. Skipping preview logic.');
      return props;
    }
    console.log('[PreviewModePlugin] Preview mode detected.');
    // If we're in Pages preview (editing) Metadata Edit Mode, prefetch the editing data
    if (isEditingMetadataPreviewData(context.previewData)) {
      console.log('[PreviewModePlugin] Detected Pages preview in Metadata Edit Mode.');

      const { site, itemId, language, version, variantIds, layoutKind } = context.previewData;
      console.log([PreviewModePlugin] Preview data received:, context.previewData);

      try {
        const data = await graphQLEditingService.fetchEditingData({
          siteName: site,
          itemId,
          language,
          version,
          layoutKind,
        });

        if (!data) {
          throw new Error(
            Unable to fetch editing data for preview ${JSON.stringify(context.previewData)}
          );
        }

        console.log('[PreviewModePlugin] Editing data successfully fetched:', data);

        const locale = context.previewData.language;
        const market = determinemarketFromLocale(locale);
        props.site = data.layoutData.sitecore.context.site as SiteInfo;
        props.layoutData = data.layoutData;
        props.dictionary = data.dictionary;
        props.headLinks = [];
        props.locale = locale;
        props.market = market;
        console.log([PreviewModePlugin] Props:, props);
        console.log([PreviewModePlugin] Context:, context);
        const personalizeData = getGroomedVariantIds(variantIds);
        console.log('[PreviewModePlugin] Groomed variant IDs:', personalizeData);

        personalizeLayout(
          props.layoutData,
          personalizeData.variantId,
          personalizeData.componentVariantIds
        );

        console.log('[PreviewModePlugin] Personalized layout data applied.');
      } catch (error) {
        console.error('[PreviewModePlugin] Error fetching editing data:', error);
        throw error;
      }

      return props;
    }

    // If we're in preview (editing) Chromes Edit Mode, use data already sent along with the editing request
    console.log(
      '[PreviewModePlugin] Detected preview mode using Experience Editor (Chromes Edit Mode).'
    );

    try {
      const data = await editingDataService.getEditingData(context.previewData);
      if (!data) {
        throw new Error(
          Unable to get editing data for preview ${JSON.stringify(context.previewData)}
        );
      }

      console.log(
        '[PreviewModePlugin] Editing data successfully retrieved from Experience Editor:',
        data
      );
      const locale = data.language;
      const market = determinemarketFromLocale(locale);
      props.site = data.layoutData.sitecore.context.site as SiteInfo;
      props.layoutData = data.layoutData;
      props.dictionary = data.dictionary;
      props.headLinks = [];
      props.locale = locale;
      props.market = market;
      console.log([PreviewModePlugin] Props:, props);
      console.log([PreviewModePlugin] Context:, context);
    } catch (error) {
      console.error('[PreviewModePlugin] Error getting editing data:', error);
      throw error;
    }

    return props;
  }
}

export const previewModePlugin = new PreviewModePlugin();

Why We Modified It:
We modified the PreviewModePlugin to set market-specific information during the preview process. This ensured that editors using the Experience Editor would see the correct variant of the content corresponding to the specified market.

Key Changes:
Personalization Handling: The plugin handles market and locale during preview to provide editors with a preview that is consistent with what end users will experience.

Final thoughts

Setting up a multisite and multilingual website for Uniworld with Sitecore XM Cloud and Next.js involved overcoming challenges around market-specific content targeting and editor experience. Here’s a summary of the key steps taken:

MarketPlugin Middleware: Handled market path redirection and cookie management to ensure users were served the correct content.
Updated next.config.js: Configured locales, rewrites, and disabled locale detection for more control.
Page Props Plugins: Updated site.ts and previewMode.ts to properly handle market and locale information, making it consistent across different page states.
Updated Page Props: Added the market context to SitecorePageProps for easy access.
This custom solution allows Sitecore XM Cloud to deliver the right content to the right users, ensuring an optimal experience for both visitors and content editors. It is modular and easily extendable, making it a strong foundation for future growth.

https://www.asuinnovation.com/blog/sitecore-xm-middleware-multi-market/

References

A Full Guide to Creating Multi-Language Sites with Sitecore XM Cloud and Next.js

Internationalization in the JSS Sample App for Next.js

Guide to Implementing Multilingual Support in Sitecore XM Cloud

The Next.js Multisite Add-On

Multisite Support with Sitecore Next.js and Edge Middleware

How to solve component refresh in Sitecore XM Cloud using Higher-Order Components

Juan Gutierrez — Fri, 04 Oct 2024 10:32:22 +0000

When working with Sitecore XM Cloud, combined with tools like Chakra UI, developers may encounter issues related to component refreshing within Sitecore Pages. One major inconvenience is that some components do not refresh automatically when changes are made, which can be frustrating, especially when aiming for a smooth workflow that allows real-time editing.

To address this issue, we reached out to Sitecore support and engaged with the Sitecore Slack community, where Jeff L'Heureux and David Ly kindly offered a solution. In this article, we will explore the problem, describe the proposed solution, and provide a step-by-step guide to enhance the editing experience in Sitecore Pages.

Best Practices: Component Class Name Requirements

According to Sitecore best practices, every component should include a class name to support the advanced editing features of XM Cloud. Class names are passed through rendering parameters, and these must be applied to the components. Creating New Components

The following structure demonstrates how to incorporate class names in a compliant manner:

<div className="{component" promo ${props.params.styles}} id="{id" ? id : undefined}>      
   <p>Component Markup Here</p> 
</div>

However, in our project, we are using Chakra UI for component styling. Chakra UI offers a highly modular and CSS-in-JS-based styling approach that provides greater control over our styles, eliminating the need to manually manage CSS class names. This reduces the risk of conflicts and makes our code cleaner and more maintainable.

In our case, we do not want to override the className attribute because it would break the structure and integration provided by Chakra UI, which relies on props to dynamically apply styles, such as Box, Flex, and other Chakra components. Instead of overriding or manually managing class names, we utilize Chakra’s prop-based styling for layout and design, which helps in maintaining consistency and flexibility across the project.

Thus, while adhering to the spirit of Sitecore’s best practices, we choose not to apply the className attribute directly. Instead, we use a customized solution to ensure that the core functionalities required by Sitecore, including rendering parameters and editing capabilities, are preserved without compromising on the styling approach provided by Chakra UI

The Problem
The main issue arises when components do not refresh correctly in Sitecore Pages while using Chakra UI to manage styles. This limitation affects real-time changes while editing the page, which can be quite disruptive. This happens even in a native Sitecore implementation, where some containers and other components do not update as expected. To solve this, we needed a reliable way to force the refresh of these components.

Here is an example of the issue before applying the solution:

Objective

Our objective is to implement a solution that forces React components to update when their parameters or styles change, ensuring that the changes are reflected automatically in Sitecore Pages without requiring manual adjustments.

Solution: Use a Higher-Order Component (HOC) to Force Updates

To solve this problem, we use a Higher-Order Component (HOC), a common pattern in React that allows extending a component's functionality without directly modifying its code. In this case, we create an HOC that monitors changes in the component's styles and forces an update.

Step-by-Step to Implement the Solution

1.Create the HOC to Detect Style Changes

The first step is to create a component called paramsWatcher. This component is responsible for wrapping any component to which we want to apply the refresh logic.

// Author: David Ly
import { useSitecoreContext } from '@sitecore-jss/sitecore-jss-nextjs';
import { ComponentProps } from 'lib/component-props';
import { useRef, useState, useEffect } from 'react';

export function paramsWatcher<P extends ComponentProps>(
  WrappedComponent: React.ComponentType<P>
) {
  function WatcherComponent(props: P) {
    const ref = useRef<HTMLDivElement>(null);
    const [styles, setStyles] = useState(props.params.Styles);

    const context = useSitecoreContext();
    const isEditing = context?.sitecoreContext?.pageEditing;

    useEffect(() => {
      if (!ref.current || !isEditing) {
        return;
      }
      console.log('Configurando el observador de mutaciones...');
      const observer = new MutationObserver((mutations) => {
        mutations.forEach((mutation) => {
          if (mutation.type === 'attributes' && mutation.attributeName === 'class') {
            const [, ...classes] = ref.current?.classList.value.split(' ') ?? [];
            console.log('Cambio detectado en las clases:', classes);
            setStyles(classes.join(' '));
          }
        });
      });
      observer.observe(ref.current, { attributes: true });
      return () => {
        console.log('Desconectando el observador de mutaciones...');
        observer.disconnect();
      };
    }, [isEditing, props.params]);

    if (!isEditing) {
      return <WrappedComponent {...props} />;
    }
    // Actualizar los estilos en los parámetros antes de renderizar
    props.params.Styles = styles;
    return (
      <>
        <div ref={ref} className={'component ' + styles} style={{ display: 'none' }} />
        <WrappedComponent {...props} />
      </>
    );
  }
  return WatcherComponent;
}

Wrap the Component We Want to Refresh Now that we have the HOC, we can use it to wrap our HeroComponent, which has issues refreshing in Sitecore Pages.

import React from 'react';
import { Image as JssImage, Text as JssText } from '@sitecore-jss/sitecore-jss-nextjs';
import { Box, Text, Flex } from '@chakra-ui/react';
import {
  AlignmentStyle,
  ColorStyle,
  HeroModel,
  UpdateHeroParams,
} from 'lib/classes/Components/Hero/HeroLib';
import { withPagesStyleChangeWatcher } from 'src/util/withPagesStyleChangeWatcher';

const HeroDefaultComponent = (): JSX.Element => (
  <Box textAlign="center">
    <Text fontSize="xl">No hay contenido disponible. Asigne una fuente de datos.</Text>
  </Box>
);

const HeroComponent = (
  model: HeroModel & { heroStyles?: { Alignment: AlignmentStyle; Color: ColorStyle } }
): JSX.Element => {
  const params =
    model.heroStyles && model.heroStyles.Alignment && model.heroStyles.Color
      ? model.heroStyles
      : UpdateHeroParams(model);

  if (model.fields && model.fields.Image && model.fields.Title) {
    return (
        <Box position="relative">
          <JssImage field={model.fields.Image} />
          <Flex
            color={{ base: 'uniblue', md: params.Color.textColor }}
            position={{ base: 'static', md: 'absolute' }}
            height="100%"
            width="100%"
            top="0"
            flexDirection="column"
            justifyContent="center"
          >
            <Box
              ml={params.Alignment.marginLeft}
              mr={params.Alignment.marginRight}
              maxW={{ base: '100%', md: '50%' }}
              textAlign="center"
            >
              <Text variant="h1" mb={0}>
                <JssText field={model.fields.Title} />
              </Text>
              <Text variant="subtitle">
                <JssText field={model.fields.Description} />
              </Text>
            </Box>
          </Flex>
        </Box>
    );
  }
  return <HeroDefaultComponent />;
};
export default paramsWatcher(HeroComponent);

Testing the Solution in Sitecore Pages Once the HOC was implemented and the component wrapped, we tested the solution in Sitecore XM Cloud Pages. Below, you can see the result after applying the solution:

Conclusion
The solution presented uses a Higher-Order Component to observe changes in the component's styles and force a refresh when necessary. By combining the power of React with observing changes in the DOM using MutationObserver, we can address the issue of components that typically do not update automatically in Sitecore.

While this is an effective solution, it is important to note that further research is required for certain types of components (like containers), and it depends on how Sitecore manages refresh in Pages. React provides a powerful tool to handle these cases, but it's essential to test and adjust accordingly.

We would like to thank Jeff L'Heureux and David Ly for his support and the Sitecore Slack community for helping us find a viable solution to this problem.

https://www.asuinnovation.com/blog/sitecore-xm-pages-hoc-for-component-refresh/

References

Creating New Components
Higher-Order Components