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 a shared Cloudinary account for image optimization. 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 — disabling the pre-configured Cloudinary image loader
- Connecting to a local hybris instance — handling self-signed TLS certificate errors in the middleware and storefront
Disabling Cloudinary for your own instance
The storefront uses Cloudinary for image optimization when the NEXT_PUBLIC_IMAGE_LOADER_FETCH_URL environment variable is set. This variable points to Alokai's shared Cloudinary account by default. When connecting to your own SAPCC instance, images won't be accessible through that account, so you should disable Cloudinary.
To disable it, remove or leave empty the NEXT_PUBLIC_IMAGE_LOADER_FETCH_URL (and NEXT_PUBLIC_IMAGE_LOADER_UPLOAD_URL) variables in both the storefront's .env and .env.example files (.env.example is used as a fallback when .env doesn't exist):
# Remove or comment out these lines:
# NEXT_PUBLIC_IMAGE_LOADER_FETCH_URL=https://res.cloudinary.com/vsf-sap/image/fetch/
# NEXT_PUBLIC_IMAGE_LOADER_UPLOAD_URL=https://res.cloudinary.com/vsf-sap/image/upload/
When NEXT_PUBLIC_IMAGE_LOADER_FETCH_URL is not set, the storefront falls back to the default image loader, which serves images directly from the remote host without any transformation.
To ensure the default image loader can construct full image URLs using transformImageUrl, you also need to set SAPCC_MEDIA_HOST in the middleware .env file. This variable is commented out by default — uncomment it and set it to your SAPCC media host URL.
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: env('NEXT_PUBLIC_IMAGE_LOADER_FETCH_URL') ? cloudinaryConfig : defaultImageConfig, images: { unoptimized: true }, };
If you've already disabled Cloudinary by removing NEXT_PUBLIC_IMAGE_LOADER_FETCH_URL, 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 image loader will work without this change.