Spartacus Release Feb’24 Updates – The SAP Composable Storefront
This article is brought by Robert Bull, Lead Solution Architect
Introduction
A number of customers have been talking about the upgrade policies defined by SAP for SAP Commerce Cloud and the Composable Storefront. I mentioned the upgrades last year in the hybrismart.com article.
Historically, since I first met hybris 4 in 2009 I have seen clients who did not upgrade their versions of SAP Commerce for years. However, that all changes with latest policy SAP have with the CCV2 environment.
These policies require that the merchant needs to keep on top of the upgrades which are currently being issued each month and therefore factor those upgrades into their development, testing and release cycles. Each release of SAP Commerce and the Composable Storefront has a 6 month validity period after which the release cannot be deployed.
A key question being asked is how onerous is this upgrading process ? and how often ? There are usually two views:
- the “little and often” approach, a view also recommended by SAP, that upgrades should be factored frequently;
- – the “if it isn’t broke don’t fix it” approach where we have seen examples SAP Commerce version they use has passed its long term support date.
In the end, it comes down to priorities and costs and we have experienced upgrade projects taking months because the version being upgraded from is quite old.
In order to get a tangible view of the current upgrading of both SAP Commerce and the Composable Storefront I decided to undertake some sample upgrades on a local version I run. For those who are interested, I use an Oracle VirtualBox VM Debian guest running in a Windows 11 host). I have traditionally built SAP Commerce using the various out-of-the-box recipes and accelerators using the instructions published by SAP. To an extent, what I am doing probably reflects what many project teams have undertaken, in that someone needs to undertake the “upgrade” user story and share with their team.
Unfortunately, I dont have the time to conduct any exhaustive local regression testing; but such testing must surely become increasingly important and the more it is automated will save the precious time and effort needed for project development and deployments.
Building Composable Storefront Libraries from Source Code
My previous local tests for hybrismart articles on the Spartacus/Composable Storefront used the SAP generated libraries that are available via SAP’s Repository Based Shipment Channel (RBSC), but it has always been feasible to build these from source code.
Up to and including Spartacus 4.3 you could retrieve the pre-built Spartacus libraries via the node registry directly, but from version 5 onwards those libraries pre-built by SAP are retrieved via the SAP proxy registry that is authenticated using a token provided by a RBSC subscription token (please re-read my previous article for more info).
However, the Composable Storefront libraries are available in all their release versions (including older Spartacus versions) in source code format from github.
The github address is: https://github.com/SAP/spartacus
SAP explains the process to build from source code in this page and it I have summarised below.
Firstly, make sure you have a compatible Angular/node installation aligning to the version of Composable Storefront you are going to build. SAP publishes the dependencies of Angular and node on their web pages. I had decided to start my tests with Composable Storefront 6.6, as it was supported with the version of SAP Commerce 2211.10 I had previously locally built only 2 months ago. According to SAP, this needs Angular 15.2.4 as the minimum required. The most recent 15.x version is strongly recommended. (Version 16 and higher is not supported). From the node perspective, it states Version 16.13.0 or a newer 16.x version. You can check with the command:
Ng version:
Creating A local Registry
In order to build using the source code approach, you first need to create a clone of the library source code but you also need a local npm-like registry to put the built libraries into. The libraries in that local registry will then be retrieved by the subsequent Composable Storefront build process. For the local registry capability I used the suggested open source product called verdaccio
Verdaccio
Verdaccio (https://verdaccio.org/) is a lightweight Node.js private proxy registry where it proxies to npm by default. Verdaccio originated as a fork from a previous package called Sinopia that had been designed to allow private registry creation, because at that time such capability was not supported on npmjs. Development of Sinopia stopped in early 2016 and Verdaccio was one of a few projects that was continued. Verdaccio also caches data from the registries that it proxies to and has its own web page allowing visibility of the libraries in its own registry.
To install and run verdaccio (at the time of writing the latest is 5.x), Node.js v12 or higher is required. I installed it globally on my local environment, and you need a command something like the following:
npm install --location=global verdaccio
verdaccio
info --- config file – /home/rob/.config/verdaccio/config.yaml
info --- the “crypt” algorithm is deprecated consider switch to “bcrypt” in the configuration file. Read the documentation for additional details
info --- using htpasswd file: /home/rob/.config/verdaccio/htpasswd
info --- plugin successfully loaded: verdaccio-htpasswd
info --- plugin successfully loaded: verdaccio-audit
warn --- http address – http://localhost:4873/ – verdaccio/5.29.0
Go to the URL shown ( http://localhost:4873/ ) and you will see an empty registry.
Later in the process, you need the ts-node TypeScript engine, therefore install it with a command like:
npm install --location=global ts-node
You now need to add a user for accessing the verdaccio registry; add the user name and password as prompted; using a command like:
npm adduser --registry http://localhost:4873
If and when you already have a registry and a user created, you can alternatively login like:
npm login --registry http://localhost:4873
you will be prompted for a username and password when logging in.
Cloning and Building the Libraries
Use git to clone the Spartacus repo from github:
git clone https://github.com/SAP/spartacus.git
Change to the new spartacus directory:
cd spartacus
Using the following command to see a list of all the branches in the repo:
git branch -a
Checkout the version you wish to build, something like:
git checkout 6.6.0
Next, install the packages and build the libraries, (it takes some minutes to complete).
npm install && npm run build:libs
This all worked well but I received warnings that node libraries 16.14 should be used and not the 16.13 as I had installed.
Testing and Publishing
The project contains a test/publication script, it can be run as follows:
ts-node ./tools/schematics/testing
The script will start verdaccio and lists a page of options to undertake. Use the cursor up/down to scroll through the options.
? What do you want to do next? …
▸ publish
build projects/schematics
build asm/schematics
build cart/schematics
build order/schematics
build checkout/schematics
build cdc/schematics
build cds/schematics
build digital-payments/schematics
build epd-visualization/schematics
build organization/schematics
build pdf-invoices/schematics
build pickup-in-store/schematics
build product/schematics
build product-configurator/schematics
build s4om/schematics
build segment-refs/schematics
build qualtrics/schematics
build requested-delivery-date/schematics
build smartedit/schematics
build storefinder/schematics
build tracking/schematics
build user/schematics
build customer-ticketing/schematics
build all libs
test all schematics
exit
The publish option will publish the libraries to your local registry, and you can see these in the verdaccio window.
Note – if you exit, then verdaccio will be stopped but you can always start it independently from command line:
verdaccio
Next, the storefrontapp will be published in the registry.
npm --registry http://localhost:4873 publish
As you can see, all the versioning shows 6.6.0 as built and published from the 6.6.0 source that was retrieved from git.
Building Composable Storefront from Local Registry Libraries
Having now built and published the libraries to the local registry, the next step is to build the Composable Storefront itself using those local libraries. The regular approach can be used:
Create the application:
ng new spartacus-local --style=scss --routing=false
cd spartacus-local
Create a file .npmrc and specify the local registry, the file has one line of text and is like:
@spartacus:registry=http://localhost:4873
Now add the schematics to the application, the .npmrc file will specify where to fetch the libraries from, and will proxy through to the node registry for other libraries. This is familiar territory for those who have installed before, you can pick and choose which libraries to add, and a choice of various modules.
ng add @spartacus/schematics
✔ Found compatible package version: @spartacus/schematics@6.5.0.
✔ Package information loaded.
The package @spartacus/schematics@6.5.0 will be installed and executed.
Would you like to proceed? Yes
✔ Packages successfully installed.
? Which Spartacus features would you like to set up?
Please note that for most Spartacus features to be properly configured, the
User-Account feature is required. Assisted Services Module, Import/Export, Saved
Cart, Quick Order, Checkout base, Cart, WishList, Order, Product – Variants,
Product – Image Zoom, SmartEdit, Store Finder, Tracking – Personalization, User
– Account, User – Profile
✅️ Added ‘@spartacus/core’ into dependencies
✅️ Added ‘@spartacus/storefront’ into dependencies
✅️ Added ‘@spartacus/assets’ into dependencies
✅️ Added ‘@spartacus/styles’ into dependencies
✅️ Added ‘@spartacus/user’ into dependencies
✅️ Added ‘@spartacus/cart’ into dependencies
✅️ Added ‘@spartacus/order’ into dependencies
✅️ Added ‘@spartacus/checkout’ into dependencies
✅️ Added ‘@spartacus/tracking’ into dependencies
✅️ Added ‘@spartacus/asm’ into dependencies
✅️ Added ‘@spartacus/storefinder’ into dependencies
✅️ Added ‘@spartacus/smartedit’ into dependencies
✅️ Added ‘@spartacus/product’ into dependencies
✅️ Added ‘@ngrx/effects’ into dependencies
✅️ Added ‘@ngrx/router-store’ into dependencies
✅️ Added ‘@ngrx/store’ into dependencies
✅️ Added ‘angular-oauth2-oidc’ into dependencies
✅️ Added ‘i18next’ into dependencies
✅️ Added ‘i18next-http-backend’ into dependencies
✅️ Added ‘i18next-resources-to-backend’ into dependencies
✅️ Added ‘@angular/service-worker’ into dependencies
✅️ Added ‘@ng-select/ng-select’ into dependencies
✅️ Added ‘ngx-infinite-scroll’ into dependencies
✅️ Added ‘@fontsource/open-sans’ into dependencies
✅️ Added ‘@fortawesome/fontawesome-free’ into dependencies
✅️ Added ‘bootstrap’ into dependencies
🩹 Downgrading ‘rxjs’ to ^6.6.0 (was 7.8.0)
CREATE src/app/spartacus/spartacus.module.ts (465 bytes)
CREATE src/app/spartacus/spartacus-features.module.ts (4105 bytes)
CREATE src/app/spartacus/spartacus-configuration.module.ts (925 bytes)
CREATE src/styles-config.scss (18 bytes)
CREATE src/app/spartacus/features/user/user-feature.module.ts (1377 bytes)
CREATE src/styles/spartacus/user.scss (58 bytes)
CREATE src/app/spartacus/features/cart/cart-base-feature.module.ts (1242 bytes)
CREATE src/styles/spartacus/cart.scss (58 bytes)
CREATE src/app/spartacus/features/cart/cart-saved-cart-feature.module.ts (807 bytes)
CREATE src/app/spartacus/features/cart/wish-list-feature.module.ts (1053 bytes)
CREATE src/app/spartacus/features/cart/cart-quick-order-feature.module.ts (820 bytes)
CREATE src/app/spartacus/features/cart/cart-import-export-feature.module.ts (846 bytes)
CREATE src/app/spartacus/features/order/order-feature.module.ts (721 bytes)
CREATE src/styles/spartacus/order.scss (59 bytes)
CREATE src/app/spartacus/features/checkout/checkout-feature.module.ts (775 bytes)
CREATE src/styles/spartacus/checkout.scss (62 bytes)
CREATE src/app/spartacus/features/tracking/personalization-feature.module.ts (578 bytes)
CREATE src/app/spartacus/features/storefinder/store-finder-feature.module.ts (801 bytes)
CREATE src/styles/spartacus/storefinder.scss (65 bytes)
CREATE src/app/spartacus/features/smartedit/smart-edit-feature.module.ts (718 bytes)
CREATE src/app/spartacus/features/product/product-variants-feature.module.ts (856 bytes)
CREATE src/styles/spartacus/product.scss (61 bytes)
CREATE src/app/spartacus/features/product/product-image-zoom-feature.module.ts (874 bytes)
CREATE src/app/spartacus/features/asm/asm-feature.module.ts (695 bytes)
CREATE src/styles/spartacus/asm.scss (57 bytes)
UPDATE src/app/app.module.ts (707 bytes)
UPDATE src/styles.scss (141 bytes)
UPDATE src/app/app.component.html (32 bytes)
UPDATE angular.json (4238 bytes)
UPDATE package.json (2027 bytes)
✔ Packages installed successfully.
Whilst this is running, if you have your verdaccio console visible, you will see it scroll messages as the libraries are pulled from the local verdaccio registry, for example:
…
…
info --- auth/allow_action: access granted to: rob
info --- allowed access for @spartacus/tracking
info --- making request: ‘GET https://registry.npmjs.org/@spartacus%2Ftracking’
http --- 304, req: ‘GET https://registry.npmjs.org/@spartacus%2Ftracking’ (streaming)
http --- 304, req: ‘GET https://registry.npmjs.org/@spartacus%2Ftracking’, bytes: 0/0
…
…
Now install anything missing:
npm install
npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE package: ‘lru-cache@10.1.0’,
npm WARN EBADENGINE required: { node: ’14 || >=16.14′ },
npm WARN EBADENGINE current: { node: ‘v16.13.2’, npm: ‘9.8.1’ }
npm WARN EBADENGINE }
up to date, audited 1063 packages in 2s
113 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
Note that warning – it is stating that one of the packages (lru-cache) now needs node 16.14 instead of 16.13 as was previously specified. In fact, I did install 16.14 and try the whole build process again but I got more compatibility warnings – I don’t have the time to fix it all at the moment, but this is an issue that I suspect will be found during these updates as the inter-dependencies of libraries is at risk because all those third party libraries have their own development roadmaps.
Now to test the application with the libraries built from source:
$ ng serve --ssl
✔ Browser application bundle generation complete.
…
…
Build at: 2024-01-19T11:40:45.678Z – Hash: e9028984440a8e60 – Time: 39924ms
** Angular Live Development Server is listening on localhost:4200, open your browser on https://localhost:4200/ **
✔ Compiled successfully.
Success !!
Updating the Composable Storefront
Back to the updating process, there are two approaches I looked at:
- updating using libraries that were locally built from source code;
- – updating from the pre-built libraries I can get from SAP (via RBSC).
According to the compatibility table in this SAP page:
I can update from 6.6 to either 6.7 or 6.8, where both are still supported to my local version of SAP Commerce 2211.10. However: it is clearly stated that:
- To update to 6.7, I have to start with a 6.6 compatible version (see this )
- – To update to 6.8, I have to start with a 6.7 compatible version (see this ).
The SAP web page for Composable Storefront 6.6, 6.7 and 6.8 states the same versions of Angular and Node, so I should not need to change anything in my local development environment.
Updating Composable Storefront from Locally Built Libraries
I will upgrade to Composable Storefront 6.7 and then to 6.8, this means that I have to build both the 6.7 libraries and the 6.8 libraries and publish in my local verdaccio registry.
Firstly, I need to checkout from git the 6.7 release branch, and then repeat the build described above and publish into the verdaccio registry.
Checkout and Build the libraries (it takes a few minutes):
git checkout 6.7.0
npm install && npm run build:libs
Publish the 6.7 libraries with the ts_node script:
ts-node ./tools/schematics/testing
Next, the 6.8 libraries
Checkout and Build the libraries (it takes a few minutes):
git checkout 6.8.0
npm install && npm run build:libs
Publish the 6.8 libraries with the ts_node script:
ts-node ./tools/schematics/testing
Now run verdaccio and publish the storefrontapp in the registry. First though, you may (probably) need to unpublish the app from verdaccio as it otherwise seen the same version and gives a publish error.
npm --registry http://localhost:4873 unpublish storefrontapp --force
npm --registry http://localhost:4873 publish
Updating the Composable Storefront from the Locally Built Libraries
First, I update to 6.7.0 by editing the file package.json, set the @spartacus libraries to “~6.7.0″,
Second, delete the node_modules folder.
Third, run:
npm install
Looking at the verdaccio console log, for example, I can see that 6.7 libraries are pulled from the registry, this is because the .npmrc file I mentioned above specifies the local verdaccio registry.
Start and run the application just to test it is still OK,
Yarn start -–ssl
Next, we repeat the process, for the 6.8 libraries.
Edit file package.json, set the @spartacus libraries to “~6.8.0″,
Delete the node_modules folder.
Run:
npm install
One additional change was necessary though, change the reference of:
@fortawesome/fontawesome-free@”6.4.2″
to
@fortawesome/fontawesome-free@”65.1”
Finally, start and run the application just to test it is still OK with the 6.8 libraries,
Yarn start -–ssl
>
Updating Composable Storefront from the SAP Built Libraries
This should be a more straightforward process without needing to build the libraries. This time, I changed the .npmrc file to specify the SAP proxy registry.
@spartacus:registry=https://73554900100900004337.npmsrv.base.repositories.cloud.sap/
//73554900100900004337.npmsrv.base.repositories.cloud.sap/:_auth=<your RBSC auth code in here>
always-auth=true
Now issue the command like:
ng update @spartacus/schematics@6.7.0 --allow-dirty
and then repeat for 6.8.0:
ng update @spartacus/schematics@6.8.0 --allow-dirty
Repository is not clean. Update changes will be mixed with pre-existing changes.
Using package manager: npm
Collecting installed dependencies…
Found 49 dependencies.
Fetching dependency metadata from registry…
Updating package.json with dependency @spartacus/schematics @ “6.8.0” (was “6.7.0”)…
Updating package.json with dependency @fortawesome/fontawesome-free @ “6.5.1” (was “6.4.2”)…
Updating package.json with dependency @spartacus/asm @ “6.8.0” (was “6.7.0”)…
UPDATE package.json (2026 bytes)
✔ Packages successfully installed.
You can see that fortawesome was automatically updated.
Finally, start and run the application just to test it is still OK with the 6.8 libraries,
Yarn start -–ssl
And success again.
Therefore, both approaches did build with a fairly straightforward process, although I recognise I am using out of the box code and not having to consider custom code.
Updating SAP Commerce
This subject has been covered many times in this web site, but a key difference now is that CCV2 has set end dates by which a specific version can be deployed. For example, on this page.
From an upgrade perspective, I am on 2211.10, and I am only going to try to upgrade to 2211.12 (note, there is no release 2211.11).
The general process is quite straightforward, described here.
But pay attention to specific notes that SAP provide in each version.
a) Create a folder where you want to extract the SAP Commerce Cloud ZIP file
b) Download the latest update release version ZIP file of SAP Commerce Cloud 2211.xx
c) Extract the ZIP file into the newly created folder
d) Back up your custom extensions (usually in <HYBRIS_HOME>/hybris/bin)
e) Delete the <HYBRIS_HOME>/hybris/bin directory of your existing installation
f) Copy the <HYBRIS_HOME>/hybris/bin directory from the update release to your existing <HYBRIS_HOME>/hybris directory
g) .Copy your custom extensions back to <HYBRIS_HOME>/hybris/bin
h) Build SAP Commerce Cloud (ant clean all)
Specifically for 2211.12:
The versions of Angular and Node are updated for smartedit, and updates can be applied if you have custom smartedits:
Check like:
ant rushcheck -Dpath=/absolute/path/smartedittools
[exec] The rush.json configuration requests Rush version 5.100.1
[exec]
[exec] Invoking “rush check”
[exec] ---------------------
[exec]
[exec]
[exec]
[exec] Rush Multi-Project Build Tool 5.100.1 – https://rushjs.io
[exec] Node.js version is 18.17.1 (LTS)
[exec]
[exec]
[exec] Starting “rush check”
[exec]
[exec] Found no mis-matching dependencies!
BUILD SUCCESSFUL
If you need to update, then please follow instructions from this page
The process so far has taken about 3 hours:
– Read the update notes
– Download the 2211.12 package
– Backup my current version
– Unzip and apply files for the updated version
– Build the updated version
– Run and perform a sanity test.
… and that does not account for any regression or other testing at this stage. In a real world, I suspect code changes would be necessary that would definitely need testing and committing to the code repo.
But am I finished ? – unfortunately not – there is a specific note related to 2211..12:
So, it looks like I should update also to 2211.13, where that release also contains only bug fixes and security improvements.
https://help.sap.com/docs/SAP_COMMERCE_CLOUD_PUBLIC_CLOUD/75d4c3895cb346008545900bffe851ce/cf1af4fe943d4e19b4d0fd006196b70d.html
– Download the 2211.13 package
– Backup my current version
– Unzip and apply files for the updated version
– Build the updated version
– Run and sanity test.
This all took another couple of hours, and running the HAC shows the versions of the extensions that the upgrade was successful.
Manifest File
When you are ready to deploy to CCV2, the manifest file in the core-customize folder can be updated to reflect the build version. See:
github.com/SAP-samples/cloud-commerce-sample-setup/…
The build manifest enable you to configure a number of build attributes by modifying various extensions, properties, aspects, and tests.
Specifically, for the commerce version:
{
“commerceSuiteVersion”: “2211.13”,
}
Likewise, for the Composable storefront, the js-storefront folder in github also has a manifest.json file, and you can specify the version of Spartacus to be included in the build.
Snippets of the file include:
“enabledRepositories”: [“spartacus-6”]
And
“nodeVersion”: “18”
Summary
This has been an interesting exercise and has given me some insight in areas of:
– Areas where development logistics can be optimised;
– The need for attention to detail in procedural activities related to updates; and,
– The need for keeping on top of the chronological validity of the Composable Storefront and SAP Commerce.
Development
Most projects I have seen (since working with hybris 4 in 2009) have needed a team of developers co-operating with each other on development, testing and deployment. A typical greenfield project can take anywhere from 9 to 18 months and in the early days it was usual that the same version of hybris was used throughout development and updates were thought about sometime after launch. Now, the situation is different:
- Updates need to be factored during the initial development because the validity period of Composable Storefront and SAP Commerce releases is 6 months;
- Updates need to be continually factored as part of post-launch BAU and roadmap activities in order for the roadmap features to be deployed.
However, updates are now less frequently seen as their own mini-project (which could take anything up to 6 months to accomplish) depending on the number of versions behind that the system is. In future, that situation should almost never arise given that the last on-prem version (2205) reaches end of mainstream maintenance in May this year and end of long term support in July 2026. All others installations should be going through the updates processes with the CCV2 environment being used.
The idea now is that accomplishing the updates in more smaller steps should be less disruptive.
To optimise this effort for development teams working on the Composable Storefront:
- If you want to build the Composable Storefront libraries from source, I suggest using a shared verdaccio registry, give someone the responsibility of building the libraries and publishing them and performing sanity tests. Better still, try to automate those tests as much as possible. The other team members can then update soon after when convenient, but it makes sense for the update to be discussed as a team effort to ensure any breaking changes are addressed soonest.
- If you want to build from the SAP Composable Storefront libraries, someone needs to manage the RBSC credentials as these also have a typical lifespan of 6 months before needing to be updated.
As I saw by just running a few tests, you need to be aware of deprecated libraries and warnings/error messages and resolve these issues.
Procedural and Chronological Activities
With the dates of releases and validity published by SAP, the development activities can be scheduled into sprint backlogs. In all versions 6.x of Composable storefront, each page describing the upgrade states you should start with the previous version. Ie, you should not be jumping from 6.2 direct to 6.8 – (I don’t know why, I suspect that it is for the dependencies assessment of various node libraries to be correctly updated in the package definition files.)
In any case, business teams need to be aware that this regular activity is scheduled:
- Maybe a single version upgrade every month; or,
- Maybe a multiple version upgrade every few months;
For SAP Commerce, the upgrade steps for each update are documented and should all be digested before commencing. In any case, this activity should also be regularly scheduled. Maybe one month you update Composable Storefront, and the next month you update SAP Commerce – it is whatever suits best but do allow plenty of time and schedule around any planned code freezes.
