Automatic Multi-Site Configuration

Caching the Site Context with Server-Side Rendering

The site can be identified during server-side rendering, and the context can be transferred to the browser using the Angular TransferState mechanism. To avoid making calls for base sites on the server side with every page request, the pages can be cached using a reverse proxy.

To allow the site to be identified on the server side, you need to provide the current request URL to composable storefront. You can do this by using the composable storefront decorator of the ngExpressEngine, which provides the SERVER_REQUEST_URL injection token under the hood. You can configure this in main.server.ts, as follows:

import { ngExpressEngine as engine } from '@nguniversal/express-engine';
import { NgExpressEngineDecorator } from '@spartacus/core';

export const ngExpressEngine = NgExpressEngineDecorator.get(engine);

Caching the Back End Response with Base Sites in PWA

When using PWA, the back end response that provides the base sites can be cached by the Angular service worker, by adding a configuration to the dataGroups array in your service worker configuration. The following is an example from ngsw-config.json:

{
  // ...
  "dataGroups": [
    // ...
    {
      "name": "basesites",
      "urls": [
        "*/rest/v2/basesites?fields=baseSites\\(uid,defaultLanguage\\(isocode\\),urlEncodingAttributes,urlPatterns,stores\\(currencies\\(isocode\\),defaultCurrency\\(isocode\\),languages\\(isocode\\),defaultLanguage\\(isocode\\)\\)*"
      ],
      "cacheConfig": {
        "maxSize": 1,
        "maxAge": "1d", // Set to 1 day. Customize this value according to your needs.
        "strategy": "performance"
      }
    }
  ]
}

In the example above, the maxAge shows a value of one day. You can customize this value according to your needs.

Note that you need to escape any parentheses with double backslashes \\, as shown in the urls configuration above. Also note that if you customize the endpoint URL in your application, you need to reflect this in the urls configuration.

For more information, see the official Angular service worker configuration documentation.

Base Sites and Storefronts

When the base site is encoded in the URL parameters, composable storefront refers to the baseSite parameter, while the CMS refers to this parameter as a storefront. You should continue to use the storefront parameter name in the CMS, because composable storefront implicitly maps storefront to baseSite. Other parameters, such as language and currency, are not affected.

Writing URL Patterns in Java

For historical reasons, regular expressions with URL patterns that are defined in the CMS are written in Java. However, these regular expressions are evaluated on the front end using JavaScript. You should continue to use Java regex in the CMS, and they will be implicitly converted to JavaScript in composable storefront. For example, for case-insensitivity, modifiers such as (?i) are mapped to /i.

For more information, see this comparison of regular expression engines in Wikipedia, and also look at the implementation of the JavaRegExpConverter service in composable storefront.

Disabling a Base Site

The back end endpoint returns a list of all base sites, without any information about whether the site is active or not, regardless of the options defined in the CMS, such as active, activeFrom, or activeTo. To disable a base site, you must remove the URL patterns for that base site.

As an alternative, low-level workaround, you can set restrictions for calls to the database in the back end to filter only active sites.

Creating a Service for a Custom Context

The following is an example of creating a service for a custom context where the ISO language code is formatted in uppercase:

export function languageToCustom(lang: string): string {
  return lang && lang.toUpperCase();
}

export function custom2Language(country: string): string {
  return country && country.toLowerCase();
}

@Injectable({ providedIn: 'root' })
export class CustomContextService implements SiteContext<string> {
  constructor(protected langService: LanguageService) {}

  getActive(): Observable<string> {
    return this.langService.getActive().pipe(map(languageToCustom));
  }

  setActive(country: string): void {
    this.langService.setActive(custom2Language(country));
  }

  getAll(): Observable<string[]> {
    return this.langService
      .getAll()
      .pipe(
        map(languages => languages.map(lang => languageToCustom(lang.isocode)))
      );
  }
}

Configuring the Custom Context

You need to fill the composable storefront configuration of context.custom with all possible valid values of the custom context. How you do this depends on whether you are using Automatic Multi-Site Configuration or Static Multi-Site Configuration. Each of these scenarios is described in the following sections.