Note: Spartacus 4.x is no longer maintained. Please upgrade to the latest version.
Note: Spartacus 4.x was tested with SAP Commerce Cloud versions 1905 to 2205. Spartacus 4.x has not been verified to work with (and is not guaranteed to work with) SAP Commerce Cloud 2211 or later releases.
Spartacus schematics allow you to install Spartacus libraries in your project. The following sections describe what the Spartacus schematics do, and also provide information about the various options and commands you can use with the schematics. If you are a developer and are looking for more technical information, see the README in the Spartacus schematics project.
Table of Contents
- Adding Spartacus Core Libraries and Features to Your Angular Project
- CMS Component Schematic
- Installing Additional Spartacus Libraries
Before using Spartacus schematics, ensure that you have all of the necessary prerequisites.
Your Angular development environment should include the following:
- Angular CLI: Version 12.0.5 or later, < 13.
- Yarn: Version 1.15 or later.
- Node.js: Version 14.15 is required. Version 12.x reached end-of-life on April 30, 2022, and is no longer supported by Spartacus. It is strongly recommended that you migrate any existing Spartacus storefronts to Node.js 14 as soon as possible. If there are any issues with Spartacus and Node.js 14, please upgrade to the latest releases. If you continue to experience issues with Node.js 14, create a support ticket with SAP.
Adding Spartacus Core Libraries and Features to Your Angular Project
You can add Spartacus core libraries and features to your Angular project by running the following command from your project root:
ng add @spartacus/schematics@latest
Note: If you are using schematics to set up your Spartacus project for the first time, there are important considerations to be aware of. For example, Spartacus does not support B2C and B2B storefronts running together in a single storefront application. For more information, see Setting Up Your Project Using Schematics.
The following is a description of the various options you can use with the
ng add @spartacus/schematics@latest command:
baseUrlsets the base URL of your CX OCC back end.
baseSiteis a comma-separated list of base site(s) to use with Spartacus.
currencyis a comma-separated list of currencies to use in Spartacus.
languageis a comma-separated list of languages to use in Spartacus.
urlParametersis a comma-separated list that represents the order of site-context parameters, such as
['baseSite', 'language', 'currency'], for example.
occPrefixsets the OCC API prefix, such as
/occ/v2/, for example.
useMetaTagsdetermines whether or not to configure the
mediaUrlin the meta tags from
featureLevelsets the application feature level. The default value is the same as the version of the Spartacus packages you are working with. For example, the
overwriteAppComponentoverwrites the content of
app.component.html. The default value is
pwaincludes progressive web application (PWA) features when building the application.
ssrincludes the server-side rendering (SSR) configuration.
lazyinstalls features with lazy loading configured for each of the feature modules. The default value is
projectallows you to specify the project that you want to configure your Spartacus application in. The default is the workspace default project.
interactiveallows you to bypass the schematics prompts and install Spartacus with a predefined set of features.
themeallows you to import the CSS for a built-in theme, such as
santorini. If you do not set a value for this parameter, the default Sparta theme is used.
The following is an example that generates an application that is ready to be used with the electronics storefront, that sets the
baseUrl and the
baseSite, and that also enables server-side rendering:
ng add @spartacus/schematics@latest --baseUrl https://spartacus-demo.eastus.cloudapp.azure.com:8443/ --baseSite=electronics-spa --ssr
Another example is the following, which generates an application that is ready to be used with both an apparel storefront and an electronics storefront, that sets the
language, and also enables server-side rendering:
ng add @spartacus/schematics@latest --baseUrl https://spartacus-demo.eastus.cloudapp.azure.com:8443/ --baseSite=apparel-uk-spa,electronics-spa --currency=gbp,usd --language=uk,en --ssr
This next example bypasses the schematics prompts and installs Spartacus with a predefined set of features:
ng add @spartacus/schematics@latest --baseUrl https://spartacus-demo.eastus.cloudapp.azure.com:8443/ --baseSite=electronics-spa --interactive=false
To see which features are included when you use the
--interactive=false flag, see schema.json.
Additional Commands for Core Libraries and Features
By default, the
ng add @spartacus/schematics command adds only a basic configuration of Spartacus. The following is a description of the commands you can use to extend your application:
ng g @spartacus/schematics:add-pwaadds a Spartacus-specific PWA module.
ng g @spartacus/schematics:add-ssradds the SSR configuration.
ng g @spartacus/schematics:add-cms-componentgenerates a CMS component, and adds the CMS component mapping to the specified module, or to a newly-generated module, if no module is specified. For more information, see CMS Component Schematic, below.
How Spartacus Schematics Work
When you run
ng add @spartacus/schematics, the command does the following:
- Adds the required dependencies.
- Sets up Spartacus modules in the project and provides the default configuration. For more information, see Reference App Structure.
- Imports Spartacus styles to
- Adds the
cx-storefrontcomponent to your
- Optionally updates
index.htmlwith the Spartacus URL endpoints in meta tags.
- If the
--pwaflag is included, it adds PWA service worker support for your project.
- If the
--ssrflag is included, the command does the following:
- Adds server-side rendering dependencies.
- Provides additional files that are required for SSR.
CMS Component Schematic
The following is a description of the available options for the CMS component schematic:
--declareCmsModulespecifies which module the newly-generated CMS component is added to. If no module is specified, a new module is generated.
--cms, injects the
CmsComponentDatainto the new component. By default, this option is set to
--cms-model, specifies the model class for the
CmsComponentData, such as
MyModel, for example. This argument is required if
--cmsComponentDatais set to
--cms-model-path, specifies the import path for the
CmsComponentData. The default is
Aside from these custom options, the
add-cms-component supports almost all options that are available for the Angular component and module schematics. The full list can be seen in this schema.json file.
The following Angular options are not supported:
- Deprecated options.
--moduleoption for components. If you want to specify an existing module for a component, use
moduleoption is only applied to the Angular
Using the ‘add-cms-component’ Schematic
The following are some examples of how the
add-cms-component schematic can be used:
ng g @spartacus/schematics:add-cms-component myAwesomeCms --cms-model=MyModelgenerates the
my-awesome-cms.component.tscomponent and the
ng g @spartacus/schematics:add-cms-component myAwesomeCms --cms-model=MyModel --declareCmsModule=my-cms-path/my-cmsgenerates the
my-awesome-cms.component.tscomponent and adds it to the specified CMS mapping for
ng g @spartacus/schematics:add-cms-component myAwesomeCms --cms-model=MyModel --module=appgenerates the
my-awesome-cms.component.tscomponent and the
my-awesome-cms.module.tsmodule, and imports them to the specified
ng g @spartacus/schematics:add-cms-component myAwesomeCms --cms-model=MyModel --module=app --declareCmsModule=my-cms-path/my-cmsgenerates the
my-awesome-cms.component.tscomponent and adds it to the specified
my-cms-path/my-cms.module.tsmodule. It also imports
my-cms.module.tsto the specified
Installing Additional Spartacus Libraries
You need to first install the Spartacus core libraries before you can install additional Spartacus libraries. For more information, see Adding Spartacus Core Libraries and Features to Your Angular Project, above.
Note: To install additional Spartacus libraries using schematics, your app structure needs to match the Spartacus reference app structure. For more information, see Reference App Structure.
Integration Libraries and Feature Libraries
During the initial set up of your storefront using schematics, you have the option to install a number of Spartacus features, which is done by installing the relevant integration or feature libraries. The following is a list of the integration libraries and feature libraries that you can install, along with information about what is included in each package.
@spartacus/asmincludes the Assisted Service Module.
@spartacus/cartincludes the Saved Cart, Quick Order, and Cart Import and Export features.
@spartacus/cdcincludes the SAP Customer Data Cloud Integration.
@spartacus/cdsincludes the Intelligent Selling Services for SAP Commerce Cloud Integration.
@spartacus/orderincludes the Order History, Replenishment Order History, and Cancellations and Returns features.
@spartacus/organizationincludes the Organization Administration and Order Approval features. Both are required for B2B Commerce Organization to work.
@spartacus/productincludes the Bulk Pricing, Variants and Image Zoom features.
@spartacus/product-configuratorincludes the Configurable Products Integration.
@spartacus/qualtricsincludes the Qualtrics Integration.
@spartacus/smarteditincludes the SmartEdit Integration.
@spartacus/storefinderincludes the Store Locator feature.
@spartacus/trackingincludes the Tag Management System feature and the Personalization Integration.
@spartacus/userincludes the Account and Profile features. The Account feature contains components such as the login form, and also exposes the general method for getting user details. The Profile feature is responsible for functionality such as closing an account, updating a profile, updating an email, updating a password, resetting a password, and registering. It is highly recommended to install both of these features.
If you do not install a particular integration library or feature library during the initial set up of your storefront, you can always install any of these libraries later on using schematics. The command to install a library is the following:
ng add <package-name>
For example, you can install the
@spartacus/asm library with the following command:
ng add @spartacus/asm
You can also include options when you use the
ng add command, as follows:
lazyinstalls features with lazy loading configured for each of the feature modules within the library. The default is
projectallows you to specify the project that you want to configure the Spartacus feature library in. The default is the workspace default project.
featuresmakes it possible to select features without the interactive prompt.
The following is an example of the
ng add command that installs Personalization without the configuration for lazy loading, and without prompting to install any of the other features from the
ng add @spartacus/tracking --lazy false --features="Personalization"