sf-b2c-controllers
Build SFRA controllers for request handling in Salesforce B2C Commerce Cloud.
Before Writing Code
Fetch live documentation FIRST:
Web-search for:
- "Salesforce B2C Commerce SFRA controllers documentation 2026"
- "SFCC server module middleware patterns"
- "B2C Commerce controller CSRF protection best practices"
Web-fetch official sources:
github.com/SalesforceCommerceCloud/storefront-reference-architecture (SFRA controllers)
- Salesforce B2C Commerce server module API reference
Verify before coding: current server module syntax, middleware chain methods, CSRF validation requirements, form validation patterns in latest SFRA.
Conceptual Architecture
Controller Basics
Controllers are route handlers defined using the server module. Routes follow the naming convention ControllerName-ActionName (e.g., Product-Show, Cart-AddProduct).
- Controller file:
controllers/Product.js
- Route:
Product-Show
- URL:
https://site.com/Product-Show?pid=12345
Every controller file ends with module.exports = server.exports();
Server Module Methods
| Method |
HTTP |
Purpose |
Example |
server.get(name, ...mw, handler) |
GET |
Display pages |
Product-Show, Cart-Show |
server.post(name, ...mw, handler) |
POST |
Form submissions |
Cart-AddProduct, Account-Register |
server.use(name, ...mw, handler) |
Any |
Shared logic, API endpoints |
Method-agnostic handlers |
Middleware Chain
Middleware functions execute left to right before the final handler. Each must call next() to continue the chain.
server.post('Action',
server.middleware.https, -> 1. Force HTTPS
csrfProtection.validateRequest, -> 2. Validate CSRF
userLoggedIn.validateLoggedIn, -> 3. Require login
function (req, res, next) {} -> 4. Handler
);
Common built-in middleware:
server.middleware.https -- force HTTPS
csrfProtection.validateRequest -- CSRF token validation
csrfProtection.generateToken -- generate CSRF token for forms
userLoggedIn.validateLoggedIn -- require authenticated user
consentTracking.consent -- consent tracking check
Extend vs Replace
| Method |
What Happens |
When to Use |
server.extend(base) |
Inherit all base routes |
Always start with this |
server.append('Route', fn) |
Run AFTER base handler |
Add data to response, logging, analytics |
server.prepend('Route', fn) |
Run BEFORE base handler |
Validation, guards, tracking |
server.replace('Route', fn) |
Completely override base |
Fundamentally different logic (rare) |
server.get/post('Route', fn) |
Define new route |
New functionality not in base |
// Pattern: Extend a base controller
var base = module.superModule;
server.extend(base);
// Fetch live docs for append/prepend behavior
Route Handling Lifecycle
HTTP Request
-> Route resolution (cartridge path, left-to-right)
-> server.use middleware (guards, validation)
-> server.prepend extensions
-> Base route handler (if extended)
-> server.append extensions
-> Response (render / json / redirect)
Response Types
| Method |
Use Case |
res.render(template, data) |
Render ISML template (HTML page) |
res.json(object) |
Return JSON (AJAX responses) |
res.redirect(url) |
HTTP redirect |
res.setStatusCode(code) |
Set HTTP status (404, 500, etc.) |
res.setViewData(data) |
Set data for middleware chain sharing |
res.getViewData() |
Get data set by previous middleware |
Route-Level Caching
Cache GET responses via property assignment on res:
| Property |
Type |
Values |
res.cachePeriod |
Number |
Duration value (e.g., 24) |
res.cachePeriodUnit |
String |
'minutes', 'hours', 'days' |
Never cache: cart, checkout, account pages. Always cache: product pages, category pages.
CSRF Protection
All state-changing requests (POST, DELETE) must validate CSRF tokens. The token is generated in the controller, passed to the ISML template as a hidden form field, and validated on submission via csrfProtection.validateRequest middleware.
Form Validation
Server-side form validation uses server.forms.getForm('formName'). Form definitions live in forms/default/*.xml. Always validate server-side -- never trust client-side validation alone.
Best Practices
Route Design
- RESTful naming:
Product-Show (view), Cart-AddProduct (action)
- Separate GET and POST -- never use
server.use for method-specific routes
- Keep controllers thin -- move business logic to models and
scripts/ helpers
Middleware
- Chain security checks before business logic (HTTPS, CSRF, auth)
- Always call
next() -- forgetting breaks the chain silently
- Create reusable middleware in
scripts/middleware/
- Use
server.middleware.https for all sensitive operations
Response Patterns
- Consistent JSON:
{ success: boolean, data?: object, errors?: array }
- Set appropriate status codes (404, 400, 500)
- Use
res.setViewData / res.getViewData to share data across middleware chain
Security
- CSRF protection on all state-changing operations
- Sanitize all user inputs (
req.querystring, req.form)
- Wrap data mutations in
Transaction.wrap()
- Log security events with
dw/system/Logger
Fetch the SFRA GitHub repository and server module API reference for exact method signatures, middleware patterns, and req/res property details before implementing.
1---2name: sf-b2c-controllers3description: Build SFRA controllers — server.get/post/use route handlers, middleware chain with server.append/prepend/replace, CSRF protection, form validation, response rendering, and route-level caching. Use when implementing request handling in B2C Commerce.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/sf-b2c-controllers7---89# sf-b2c-controllers1011Build SFRA controllers for request handling in Salesforce B2C Commerce Cloud.1213## Before Writing Code1415**Fetch live documentation FIRST:**16171. **Web-search** for:18 - "Salesforce B2C Commerce SFRA controllers documentation 2026"19 - "SFCC server module middleware patterns"20 - "B2C Commerce controller CSRF protection best practices"21222. **Web-fetch** official sources:23 - `github.com/SalesforceCommerceCloud/storefront-reference-architecture` (SFRA controllers)24 - Salesforce B2C Commerce server module API reference25263. **Verify** before coding: current server module syntax, middleware chain methods, CSRF validation requirements, form validation patterns in latest SFRA.2728## Conceptual Architecture2930### Controller Basics3132Controllers are **route handlers** defined using the `server` module. Routes follow the naming convention `ControllerName-ActionName` (e.g., `Product-Show`, `Cart-AddProduct`).3334- Controller file: `controllers/Product.js`35- Route: `Product-Show`36- URL: `https://site.com/Product-Show?pid=12345`3738Every controller file ends with `module.exports = server.exports();`3940### Server Module Methods4142| Method | HTTP | Purpose | Example |43|--------|------|---------|---------|44| `server.get(name, ...mw, handler)` | GET | Display pages | `Product-Show`, `Cart-Show` |45| `server.post(name, ...mw, handler)` | POST | Form submissions | `Cart-AddProduct`, `Account-Register` |46| `server.use(name, ...mw, handler)` | Any | Shared logic, API endpoints | Method-agnostic handlers |4748### Middleware Chain4950Middleware functions execute **left to right** before the final handler. Each must call `next()` to continue the chain.5152```53server.post('Action',54 server.middleware.https, -> 1. Force HTTPS55 csrfProtection.validateRequest, -> 2. Validate CSRF56 userLoggedIn.validateLoggedIn, -> 3. Require login57 function (req, res, next) {} -> 4. Handler58);59```6061Common built-in middleware:62- `server.middleware.https` -- force HTTPS63- `csrfProtection.validateRequest` -- CSRF token validation64- `csrfProtection.generateToken` -- generate CSRF token for forms65- `userLoggedIn.validateLoggedIn` -- require authenticated user66- `consentTracking.consent` -- consent tracking check6768### Extend vs Replace6970| Method | What Happens | When to Use |71|--------|-------------|-------------|72| `server.extend(base)` | Inherit all base routes | Always start with this |73| `server.append('Route', fn)` | Run AFTER base handler | Add data to response, logging, analytics |74| `server.prepend('Route', fn)` | Run BEFORE base handler | Validation, guards, tracking |75| `server.replace('Route', fn)` | Completely override base | Fundamentally different logic (rare) |76| `server.get/post('Route', fn)` | Define new route | New functionality not in base |7778```javascript79// Pattern: Extend a base controller80var base = module.superModule;81server.extend(base);82// Fetch live docs for append/prepend behavior83```8485### Route Handling Lifecycle8687```88HTTP Request89 -> Route resolution (cartridge path, left-to-right)90 -> server.use middleware (guards, validation)91 -> server.prepend extensions92 -> Base route handler (if extended)93 -> server.append extensions94 -> Response (render / json / redirect)95```9697### Response Types9899| Method | Use Case |100|--------|----------|101| `res.render(template, data)` | Render ISML template (HTML page) |102| `res.json(object)` | Return JSON (AJAX responses) |103| `res.redirect(url)` | HTTP redirect |104| `res.setStatusCode(code)` | Set HTTP status (404, 500, etc.) |105| `res.setViewData(data)` | Set data for middleware chain sharing |106| `res.getViewData()` | Get data set by previous middleware |107108### Route-Level Caching109110Cache GET responses via property assignment on `res`:111112| Property | Type | Values |113|----------|------|--------|114| `res.cachePeriod` | Number | Duration value (e.g., `24`) |115| `res.cachePeriodUnit` | String | `'minutes'`, `'hours'`, `'days'` |116117Never cache: cart, checkout, account pages. Always cache: product pages, category pages.118119### CSRF Protection120121All **state-changing requests** (POST, DELETE) must validate CSRF tokens. The token is generated in the controller, passed to the ISML template as a hidden form field, and validated on submission via `csrfProtection.validateRequest` middleware.122123### Form Validation124125Server-side form validation uses `server.forms.getForm('formName')`. Form definitions live in `forms/default/*.xml`. Always validate server-side -- never trust client-side validation alone.126127## Best Practices128129### Route Design130- RESTful naming: `Product-Show` (view), `Cart-AddProduct` (action)131- Separate GET and POST -- never use `server.use` for method-specific routes132- Keep controllers thin -- move business logic to models and `scripts/` helpers133134### Middleware135- Chain security checks before business logic (HTTPS, CSRF, auth)136- Always call `next()` -- forgetting breaks the chain silently137- Create reusable middleware in `scripts/middleware/`138- Use `server.middleware.https` for all sensitive operations139140### Response Patterns141- Consistent JSON: `{ success: boolean, data?: object, errors?: array }`142- Set appropriate status codes (404, 400, 500)143- Use `res.setViewData` / `res.getViewData` to share data across middleware chain144145### Security146- CSRF protection on all state-changing operations147- Sanitize all user inputs (`req.querystring`, `req.form`)148- Wrap data mutations in `Transaction.wrap()`149- Log security events with `dw/system/Logger`150151Fetch the SFRA GitHub repository and server module API reference for exact method signatures, middleware patterns, and req/res property details before implementing.