sfcc-sfra-client-side-js

SFRA Client-Side JavaScript

Guide for building and extending client-side functionality in SFRA storefronts.

Quick Checklist

[ ] Use `paths` alias for base extension, never edit app_storefront_base
[ ] Register assets in main request context, not remote includes
[ ] Compose client overrides—no `module.superModule` (server-only)
[ ] Generate controller URLs server-side; pass via `data-*`
[ ] Always include CSRF token on POST (form.serialize() or manual)
[ ] Cache selectors & delegate events for dynamic regions
[ ] Batch DOM updates; debounce high-frequency handlers
[ ] Escape dynamic data inserted into DOM (XSS prevention)
[ ] Provide keyboard & screen reader accessible interactions
[ ] Namespace events for clean teardown

Architecture Overview

SFRA separates:

• Server runtime resolution (cartridge path in BM) – affects controllers, scripts, ISML
• Client build resolution (compile-time paths aliases) – affects client/default/

Client behavior is determined at build time, not by the live cartridge path.

Directory Structure

app_custom_mybrand/
    cartridge/
        client/
            default/
                js/           # Feature modules
                scss/         # Sass source

Guidelines:

• Never modify app_storefront_base directly
• Mirror base file locations when extending
• Group by domain (product/, checkout/)

Build Process

npm run compile:js
npm run compile:scss

Key distinction: Changing the BM cartridge path does not affect already compiled bundles. Recompile after structural changes.

Asset Loading

Register assets in ISML:

assets.addJs('/js/product/detail.js');
assets.addCss('/css/product.css');

Caveat: Assets added inside remote includes live only in that request and won't appear in the parent page.

Client-Side Extension

Extension uses build-time composition, not runtime inheritance.

1. Configure paths in package.json

{
    "paths": {
        "base": "../storefront-reference-architecture/cartridges/app_storefront_base/"
    }
}