This practical guide covers the steps for installing the current version of Composable Storefront on SAP Commerce. Using a standard commerce recipe, it outlines the edits needed on Composable Storefront (aka Spartacus) to support features like SmartEdit, personalization, and the ASM.
Installing SAP Commerce Cloud
We will start by installing SAP Commerce Cloud 2211, patch 20. You can try a later patch, but your mileage may vary. We'll create a recipe based on the cx recipe.
After downloading SAP Commerce Cloud 2211.20, make a copy of the cx recipe and name it (for example) mycx. Then edit this recipe's build.gradle file.
In that file, uncomment the line: extName 'spartacussampledata'.
To speed up the installation process, comment out the following test extensions:
extName 'b2bocctests'
extName 'b2bpunchoutocctests'
extname 'chineseaddressocctests'
extName 'commercewebservicestests'
extName 'configurablebundleocctests'
extName 'customerticketingocctests'
extName 'sapproductconfigocctests'
extName 'textfieldconfiguratortemplateocctests'
extName 'yocctests'
Then add the following properties ( to improve performance and help Spartacus run correctly):
// Improve build performance
property 'build.parallel', 'true'
// commented out because otherwise initialization takes much longer; if I change my mind, I can always activate it later
property '#backoffice.cockpitng.development.mode', 'true'
property '#for activating breadboard',''
// allow background indexing
property 'backoffice.search.background.solr.indexing.enabled', 'true'
property 'backoffice.solr.search.index.autoinit', 'true'
// Need higher value to avoid 'thread exceeded exception' when publishing promotions rules using cronjobs
property 'ruleengineservices.cronjob.concurrent.max', '10'
// Enable SmartEdit page structure feature
property 'smartedit.pagetree.enabled', 'true'
property 'smarteditaddon.dynamicattribute.enabled', 'true'
// Speed up SmartEdit build time
property 'smartedittools.only.build.once', 'true'
property 'initialpassword.admin', 'nimda'
// Configure Silent Order Post
property 'sop.post.url', 'https://localhost:9002/acceleratorservices/sop-mock/process'
// Cross-Origin Resource Sharing (CORS) settings that you can configure to use with a trusted third-party web application (Spartacus)
// These should be adjusted to be more restrictive in a production environment
property 'corsfilter.acceleratorservices.allowedOrigins', '*'
property 'corsfilter.assistedservicewebservices.allowedHeaders', 'origin content-type accept authorization cache-control x-anonymous-consents x-profile-tag-debug x-consent-reference'
property 'corsfilter.assistedservicewebservices.allowedOrigins', '*'
property 'corsfilter.assistedservicewebservices.exposedHeaders', 'x-anonymous-consents'
property 'corsfilter.commercewebservices.allowedHeaders', 'origin content-type accept authorization cache-control x-anonymous-consents x-profile-tag-debug x-consent-reference occ-personalization-id occ-personalization-time'
property 'corsfilter.commercewebservices.allowedOrigins', '*'
property 'corsfilter.commercewebservices.exposedHeaders', 'x-anonymous-consents occ-personalization-id occ-personalization-time'
property 'corsfilter.default.allowedOrigins', '*'
property 'corsfilter.permissionswebservices.allowedOrigins', '*'
property 'corsfilter.ycommercewebservices.allowedHeaders', 'origin content-type accept authorization cache-control x-anonymous-consents x-profile-tag-debug x-consent-reference'
property 'corsfilter.ycommercewebservices.allowedOrigins', '*'
property 'corsfilter.ycommercewebservices.exposedHeaders', 'x-anonymous-consents'
Save the build.gradle file.
The Spartacus sample data extension is not included in your installation. You'll need to download it from https://sap.github.io/spartacus-docs/spartacussampledata-extension/ -- then place the unzipped content in hybris/bin/custom/spartacussampledata (create the custom directory if needed).
Now install and initialize SAP Commerce Cloud using the mycx recipe. While it's initializing, you can turn you attention to installing Spartacus.
Installing Composable Storefront (aka Spartacus)
1. Preparation
Install the following software on your computer. There is an installer for the first (node.js), and you can install the others from the command line (Terminal on MacOs/Linux, cmd on Windows). On MacOS/Linux, you may need to prefix the installation commands with sudo to run them with administrator privileges.
Node.js (version 20.9 or higher)
- Download and the the .pkg (MacOS) or .msi (WIndows) file from https://nodejs.org/en/download
Yarn (version 1.15 or higher)
- Install with npm install -g yarn
Angular CLI (version 17.0 or higher)
- Install with npm install -g @angular/cli@17.0.5
Git (if you don't already have it installed)
- Download from https://git-scm.com/downloads
In a Terminal or cmd window, execute the following commands to verify you have the correct versions of the necessary software:
node -v
v20.11.1
yarn -v
1.22.19
ng version
Angular CLI: 17.0.5
git --version
git version 2.15.0
You'll need a decent text editor, such as an Integrated Development Environment (IDE). In this guide, I'll be using Visual Studio Code, which I downloaded from https://code.visualstudio.com/download
2. Generating a New Angular Application
Open a Terminal (or cmd) window and navigate to the location of your choice (for example, create a folder under your SAP Commrece Cloud root folder named spartacus). Generate a new Angular application with the following command: ng new mystore2211 --style=scss --routing=false --standalone=false
You can navigate to the newly created mystore2211 directory to check what was generated:
3. Obtaining Credentials from the Repository-Based Shipment Channel
To install Composable Storefront 2211, you will need to download the appropriate libraries from the Repository-Based Shipment Channel (RBSC). We'll do that in the next section, but we first need to generate credentials to access the channel.
Log in to the RBSC ( https://ui.repositories.cloud.sap/www/webapp/users/ ) using an S-user that has the appropriate licenses to download the Composable Storefront libraries. (If you are an SAP Employee, log in using your I-user or D-user number.)
If you logged in using an S-user account, ensure that you can see the Composable Storefront License in the list of licenses. If not, you will get an error when trying to download the packages.
Once logged in, you need a technical user in the repository. If you don't already have one, click the Add User button to create one. Pick a username, which will be prefixed by your company id. (When I created a technical user named pierre, the repository generated the username sap-pierre.)
Now that you have a user in the repository, click on this user in the User Management tab. On the right of the window, you will see the various credentials or tokens that were generated for this user.
Using your editor, create a plaintext file named .npmrc (notice it starts with a period) in the mystore2211 directory. Copy the following content verbatim and paste it inside that file.
@spartacus:registry=https://73554900100900004337.npmsrv.base.repositories.cloud.sap/
//73554900100900004337.npmsrv.base.repositories.cloud.sap/:_auth=<npmcredentialsfromrbsc>
always-auth=true
You will have noticed that it contains a placeholder. We'll now go grab an authorization token to replace it.
Return to the browser page showing the RBSC repository where your technical user has been selected, and click the copy icon on the far right (beside the Regenerate button) to copy the generated NPM Base64 Credentials.
In the .npmrc file you're editing, replace the string <npmcredentialsfromrbsc> with the NPM Base64 Credentials you just copied, and save the file.
Great! You're ready to download the Spartacus libraries.
4. Downloading the Composable Storefront Libraries
In your Terminal (or cmd) window, make sure you are in the mystore2211 folder before executing the following command:
ng add @spartacus/schematics@2211.20 --no-interactive
The schematics tool adds the core Composable Storefront files and configurations needed by the SAP Commerce Cloud sample stores.
We use the --no-interactive flag to bypass the schematics prompts and install the composable storefront with default features. If you omit this flag, you'll be asked to choose which features you want to set up. This gives you an opportunity to specify B2B features, for instance. However, keep in mind that Composable Storefront cannot act as a front end for both B2C and B2B storefronts. If your SAP Commerce Cloud site has both B2C and B2B stores, you will need each served by its own instance of Composable Storefront.
If you specify any of the following features, your composable storefront will automatically become a B2B storefront, and will no longer correctly support the B2C storefront.
- Organization - Administration
- Organization - Order Approval
- Product - Bulk Pricing
- Product Configurator - CPQ Configurator
In this guide, I am concentrating only on the B2C storefronts: the Electronics and Apparel stores.
Back to your Terminal (or cmd) window, enter the following command: yarn install
When that completes, we're going to have to add some configuration. Edit the mystore2211 directory in your IDE. If you've configured Visual Studio Code to allow command-line invocation, you can navigate to the mystore2211 directory and enter: code . (that's code followed by a period).
Open src/app/spartacus/spartacus-configuration.module.ts and verify that the following configurations are present:
- baseURL: Points to your SAP Commerce Cloud server, by default it’s https://localhost:9002.
- features.level: Defines the compatibility level.
You will also need to add the following configurations:
- context: Defines the site context such as base site, language, and currency
- asm: After importing AsmConfig, add an entry to enable the userIdHttpHeader to support the Assisted Service Module.
Here is a sample configuration fragment, omitting the imports prior to the one you need to add, and ending with the start of the i18n config (the remainder of the file is omitted):
...
import { AsmConfig } from '@spartacus/asm/root';
@NgModule({
declarations: [],
imports: [
],
providers: [provideConfig(layoutConfig),
provideConfig(mediaConfig), ...defaultCmsContentProviders, provideConfig(<OccConfig>{
backend: {
occ: {
baseUrl: 'https://localhost:9002',
}
},
}), provideConfig(<SiteContextConfig>{
context: {
currency: ['USD', 'JPY', 'GBP'],
language: ['en', 'de', 'ja', 'zh'],
baseSite: ['electronics-spa', 'apparel-uk-spa'],
urlParameters: ['baseSite', 'language', 'currency']
},
}), provideConfig(<AsmConfig>{
asm: {
userIdHttpHeader: {
enable: true
},
},
}), provideConfig(<I18nConfig>{
...
Additional configuration for ASM
The Assisted Service Module needs additional configuration.
Edit the hybris/config/local.properties file and replace the following entry:
corsfilter.commercewebservices.allowedHeaders=origin content-type accept authorization cache-control if-none-match x-anonymous-consents x-profile-tag-debug x-consent-reference occ-personalization-id occ-personalization-time sap-commerce-cloud-user-id
For Windows users
One of my colleagues on Windows ran into this issue, which I expect will be resolved eventually. If it hasn't, then read on for an easy fix.
The creators of Microsoft Windows seemed keen on not being Unix, so they chose to use a backslash as a directory separator. Unfortunately, the backslash is a character Unix systems interpret as an escape character, and Spartacus uses the Unix definitions for back and forward slashes. Consequently, if you're installing Spartacus on Windows, you must modify all the files in mystore2211/src/styles/spartacus. They’re named asm.scss, cart.scss, checkout.scss, etc. In each of these files, change the \ (backslash) characters to a / (forward slash):
to
5. SmartEdit Integration
Still using your IDE (in this example, Visual Studio Code), you need to copy the webApplicationInjector.js file to your assets folder.
Copy node_modules/@spartacus/smartedit/assets/webApplicationInjector.js
to the src/assets folder.
6. Personalization
In your IDE, open src/app/spartacus/features/tracking/personalization-feature.module.ts and add the following import statement and PersonalizationConfig to enable the personalization mode in Composable Storefront.
Add the 10 lines below, shown in context (these lines include the import, and an entire provideConfig section, for PersonalizationConfig, which you need to place inside the providers array):
...
import { PersonalizationConfig } from "@spartacus/tracking/personalization/root";
@NgModule({
declarations: [],
imports: [
PersonalizationRootModule
],
providers: [provideConfig(<CmsConfig>{
...
},
}
}),
provideConfig(<PersonalizationConfig>{
personalization: {
enabled: true,
httpHeaderName: {
id: 'Occ-Personalization-Id',
timestamp: 'Occ-Personalization-Time',
},
},
}),
]
})
export class PersonalizationFeatureModule { }
...
Common mistake: Make sure you didn't forget the import statement at the beginning...
7. Starting the Composable Storefront Application
In your Terminal (or cmd) window, make sure you're still in the mystore2211 folder. Then launch the Composable Storefront with the following command: yarn start --ssl
The Composable Storefront application will be compiled, then started in the Angular Live Development Server. The ssl switch allows the storefront application to be served over the secure HTTPS protocol.
Caution! You're not done yet. Please complete the next section. You may encounter up to three issues using SmartEdit. If you encounter any of them, please complete the additional configuration steps provided.
8. Verification
Before verifying that your Composable Storefront is running correctly, the commerce server needs to be running. If it isn't, please launch it now.
Once SAP Commerce Cloud is fully up and running, navigate to one of the following URLs:
You will likely get a security warning about certificates (due to the fact that you're on localhost); accept the warning and proceed to the page anyway. You should see one of the following pages:
Using SmartEdit
Provided you completed Step 5 above, your Composable Storefront should be integrated with SmartEdit, allowing you to manage the storefront's WCMS components in SmartEdit, in the same way you used to in the Accelerator storefront.
Navigate to https://localhost:9002/smartedit and log in as admin. Now, one of two things will happen:
A. You get an error trying to log in
If that happens, run the following ImpEx statement in the HAC (Hybris Administration Console):
INSERT_UPDATE OAuthClientDetails;clientId[unique=true];resourceIds;scope[mode=append];authorizedGrantTypes;accessTokenValiditySeconds;authorities;clientSecret;
;smartedit;hybris;basic,permissionswebservices,previewwebservices;password,client_credentials;3600;;;
Then try logging in again.
B. You log in without any issue
Select Spartacus Electronics Site in the Site dropdown.
You will see the Staged and Online content catalog versions for the Electronics Composable Storefront:
Click on the Homepage link in the Staged catalog version to see the homepage's content slots and components:
Oops! First Potential Issue
If the following appears instead of the homepage:
Then you need to correctly set the WCMS Cockpit Preview URL, as follows:
- In Backoffice ( https://localhost:9001/backoffice, login as admin ), navigate to WCMS > Website > electronics-spa, and click the WCMS Properties tab.
- Set the WCMS Cockpit Preview URL to match your composable storefront web site, which is https://localhost:4200/electronics-spa/en/USD
After setting the preview URL, please log out of SmartEdit (click on the account management at the top right of the SmartEdit window and click on Sign out) then log back in as admin. When you click on Homepage again, it should display correctly.
Perform the same test for the apparel store. If the same issue crops up, navigate to WCMS > Website > apparel-uk-spa and set the WCMS Cockpit Preview URL to https://localhost:4200/apparel-uk-spa/en/USD/.
If you're still having issues correctly seeing the homepage in SmartEdit, you can try the following steps:
- Sign in to SmartEdit as the admin user
- Click the Settings icon in the top right
- In the Configuration Editor, scroll down to whiteListedStorefronts and add the exact URL of your Composable Storefront ( for example, https://localhost:4200 )
The homepage should now appear correctly in SmartEdit
Darn! Second Potential Issue
It's likely the mode's tool bar will not correctly display when you view the homepage in SmartEdit, preventing you from switching modes (i.e., from Preview to Basic Edit mode). For example:
If that happens, you need to change the placeholder values for storefrontPreviewRoute and allowOrigin.
In your IDE, open src/app/spartacus/features/smartedit/smart-edit-feature.module.ts and update the SmartEdit configuration as shown below:
...
provideConfig(<SmartEditConfig>{
smartEdit: {
storefrontPreviewRoute: 'cx-preview',
allowOrigin: 'localhost:9002',
},
})
,,,
When you've saved the file, refresh SmartEdit, and the toolbar should now appear correctly.
Well, that's it. I hope you found this guide useful.
- SAP Managed Tags:
4 Comments
