Building storefronts with SAP Commerce Cloud Spartacus

Spartacus is a lightweight, open-source framework for building online ecommerce storefronts for SAP Commerce Cloud. Spartacus is based on JavaScript and Angular and is published as libraries. Developers can import Spartacus into existing applications to have tools run out of the box for storefronts.

In this article, we’ll introduce some of the features of Spartacus, discuss how to get started with a storefront application, and cover some tips and tricks.

Spartacus features

Two primary advantages of leveraging Spartacus are its extendability and its ability to be upgraded. The open-source libraries are updated frequently — about every two weeks — so developers can quickly take advantage of upgrades and new features. Since Spartacus works purely through REST API calls to SAP Commerce Cloud, the storefront runs independently of any backend architecture.

The Spartacus framework supports progressive web applications (PWA). PWAs incorporate responsive design elements that allow customers to leverage storefronts on mobile and desktop platforms without developers programming extra frontend features.

Spartacus interfaces well with various content management systems (CMS) and is fully supported to provide personalized experiences. Spartacus was designed for ecommerce storefronts and is easily integrated with SmartEdit. SmartEdit includes a feature to preview Spartacus sites as they will appear to customers.

Dependencies

Spartacus is supported by an Angular platform on the frontend. It also uses yarn and Node.js.

Different versions of Spartacus require specific versions of Angular, Node.js, and yarn, so it’s best to check the requirements.

On the backend, Spartacus interfaces with the SAP Commerce Cloud. Version 2005 of the SAP Commerce Cloud is recommended, but Spartacus will work with versions 1905 and higher.

Getting started

To install Spartacus, import libraries to existing JavaScript or Angular web applications. In the example below, we’ll explain how to install Spartacus into an existing Angular project using schematics.

Prerequisites

For the workflow below, the following prerequisites are necessary:

• Angular CLI version 9.1 or higher but less than 10.0
• Angular 9 or higher but less than 10.0
• Node version is less than or equal to 13

Workflow and examples

Adding Spartacus libraries

To import Spartacus libraries into an Angular project, open a command prompt and change the directory to your project directory. From there, type the following command into the prompt:

ng add @spartacus/schematics

This command adds a basic configuration, but can be expanded for customizations.

For example, adding a parameter for baseUrl sets the base URL of the CX OCC backend. Other parameters like currency or language set the defaults in the storefront. A full listing of available parameters is offered with the Spartacus documentation.

Beyond parameters, the base command can be expanded further to extend the application. Here are a few examples:

• ng g @spartacus/schematics:add-ssr (configures server-side rendering)
• ng g @spartacus/schematics:add-pwa (includes a PWA module customized for Spartacus)
• ng g @spartacus/schematics:add-cms-component (creates a CMS component and adds the component)

What’s happening behind the scenes

When the base command is run, several steps happen behind the scenes to get Spartacus set up in your project:

• Required dependencies are added to the project
• Spartacus modules are imported into app.module and the default configuration is set
• Spartacus styles are imported into main.scss
• cx-storefront component is added to app.component

Additional steps occur if you add parameters or flags like PWA or SSR — for example, adding server-side rendering dependencies and additional files needed for configuration.

CMS component setup

One of the most important steps of setting up a new ecommerce site is getting inventory included, so Spartacus schematics support adding CMS components.

While add-cms-component handles almost all CMS setup, certain customizations are also available, most of which relate to the CMD component data.

• --declareCmsModule: Identifies where the new CMS component is added. If an existing module is not specified, the setup generates a new module.
• --cmsComponentData (also --cms): Defaults to true. This option adds CmsComponentData into the new component.
• --cmsComponentDataModel (also --cms-model): Identifies the model class for CmsComponentData. This argument is required if --cmsComponentData is set to true.
• --cmsComponentDataModelPath(also --cms-model-path): Specifies the path for importing CmsComponentData. The default is set to @spartacus/core.

Here’s an example of using add-cms-component with --declareCmsModule:

ng g @spartacus/schematics:add-cms-component mySiteCms
--cms-model=MySiteModel --module=app
--declareCmsModule=my-site-cms-path/my-site-cms

The statement above creates the necessary component.ts file and adds the file to the user-specified module location at my-site-cms-path/my-site-cms.module.ts. The command also imports my-site-cms.module.ts to app.module.ts.

After the site is set up, the CMS can still be customized for personalized experiences through various JavaScript, Angular, and CSS changes. The Spartacus documentation includes additional information on customizing CMS components.

Customizing Spartacus

Page customization

Spartacus supports pages even though it is a single-page application (SPA). Pages in Spartacus are controlled by the CMS, so any additions or edits to pages are made on the CMS side.

Banners

Spartacus leverages the banner component to render banners created in the CMS. Banners can have one or more images and may contain optional content like a header. They are often used to link additional content.

Banners can be mapped with Spartacus like this:

    SimpleResponsiveBannerComponent: {
      component: BannerComponent
    },
    BannerComponent: {
      component: BannerComponent
    },
    SimpleBannerComponent: {
      component: BannerComponent
    }
  }
}

Search box

Adding a search box component enables two important features for user searches: autocomplete and searching the product catalog without leaving the page. The search box component is added to a JavaScript component like this:

        SearchBoxComponent: {
          component: SearchBoxComponent
        }
    }
}

This can be edited for customizing search functionality.

Tips and tricks

Recipe modules

Spartacus sets recipe modules in src/app/app.module.ts that provide a base implementation. Currently, B2cStorefrontModule is the most popular recipe module. However, using another recipe module like StorefrontModule or StorefrontFoundationModule could be a better fit for your site if you need additional flexibility for deeper customizations. These are worth researching to see what the best fit for your site is.

Referencing libraries

We recommend referencing Spartacus libraries for further customizations. Although it may be tempting to copy and paste Spartacus source code into your project, there are other, cleaner ways to customize your storefront — for example, editing CMS content.

Conclusion

Spartacus is an open-source library for storefronts using SAP Commerce Cloud. In this article, we covered several basic features of Spartacus as well as how to incorporate it with an existing website. We covered several examples of how to customize Spartacus for CMS, banners, and search functionality. We also covered a few tips and tricks for working with Spartacus.

For additional information on using Spartacus and customizing your storefront, visit the official Spartacus documentation.