Local development with a custom SAPCC instance
By default, the Alokai SAPCC storefront is pre-configured to use Alokai's demo SAP Commerce Cloud instance, including the Alokai Image Optimizer pointed at the demo media host. When you want to connect to your own SAPCC instance - especially a local hybris installation - you'll need to adjust a few settings to avoid certificate errors and image loading failures.
This guide covers two common scenarios:
- Using your own SAPCC instance - pointing the image optimizer at your own media host (or disabling it)
- Connecting to a local hybris instance - handling self-signed TLS certificate errors in the middleware and storefront
Pointing the image optimizer at your own instance
The storefront optimizes images through the Alokai Image Optimizer when the NEXT_PUBLIC_COMMERCE_MEDIA_HOST environment variable is set. Image URLs that start with that host are rewritten to /img-proxy/commerce/... and proxied through the optimizer. By default it points at Alokai's demo media host, so when connecting to your own SAPCC instance you should set it to your own media origin - or leave it empty to skip optimization entirely.
Set NEXT_PUBLIC_COMMERCE_MEDIA_HOST to your instance's media origin in both the storefront's .env and .env.example files (.env.example is used as a fallback when .env doesn't exist):
NEXT_PUBLIC_COMMERCE_MEDIA_HOST=https://your-sapcc-instance.example.com
When NEXT_PUBLIC_COMMERCE_MEDIA_HOST is left empty, the loader passes image URLs through untouched, serving images directly from the remote host without any transformation.
SAPCC returns relative media paths, so the middleware requires SAPCC_MEDIA_HOST to turn them into absolute URLs - it is set to the demo instance by default and the middleware fails to start without it. Point it at your own SAPCC media origin (the same origin as SAPCC_API_URI). To also optimize those images, set the storefront's NEXT_PUBLIC_COMMERCE_MEDIA_HOST to the same origin.
Connecting to a local hybris instance
Local hybris instances typically use self-signed SSL certificates, which Node.js rejects by default. This affects both the middleware (which makes server-to-server requests to the SAPCC API) and the Next.js storefront (which loads product images).
Middleware - bypass TLS certificate validation
Add the following to the middleware .env file to allow the middleware to connect to a local instance with a self-signed certificate:
NODE_TLS_REJECT_UNAUTHORIZED=0
Development only
Setting NODE_TLS_REJECT_UNAUTHORIZED=0 disables TLS certificate validation entirely. Never use this in a production environment. It makes your application vulnerable to man-in-the-middle attacks.
Storefront - disable Next.js image optimization
When images are served from a local hybris instance over HTTP or with a self-signed certificate, Next.js image optimization will fail. Disable it by replacing the images configuration in your next.config.mjs with unoptimized: true:
const nextConfig = {
// ...
images: { loader: 'custom', loaderFile: './config/image-optimizer.ts', remotePatterns: [{ hostname: '*', protocol: 'https' }] }, images: { unoptimized: true }, };
If you've already left NEXT_PUBLIC_COMMERCE_MEDIA_HOST empty, you only need to add unoptimized: true when your local hybris instance uses HTTP or a self-signed certificate. If it uses a valid HTTPS certificate, the default loader will pass images through without this change.