Sfcc Sfra Controllers

SFRA Controllers Skill

This skill guides you through creating storefront controllers for Salesforce B2C Commerce using the Storefront Reference Architecture (SFRA).

Overview

Controllers are JavaScript modules that handle storefront requests. A controller URL has this structure:

https://{domain}/on/demandware.store/Sites-{SiteName}-Site/{locale}/{ControllerName}-{FunctionName}

Example: https://example.com/on/demandware.store/Sites-RefArch-Site/en_US/Home-Show

MVC Pattern

SFRA uses Model-View-Controller pattern:

• Controller (/controllers): Handles requests, calls models, determines view
• Model (/models): Business logic, returns JSON objects
• View (/templates): ISML templates, renders pdict data only

Cartridge Path: Custom cartridges must precede app_storefront_base to override functionality. Never edit the base cartridge directly.

File Location

Controllers reside in the cartridge's controllers directory:

/my-cartridge
    /cartridge
        /controllers
            Home.js           # URL: Home-{function}
            Product.js        # URL: Product-{function}
            Cart.js           # URL: Cart-{function}

Basic Controller Pattern

'use strict';

var server = require('server');

// Handle GET request
server.get('Show', function (req, res, next) {
    res.render('home/homepage');
    next();
});

// Handle POST request
server.post('Subscribe', function (req, res, next) {
    var email = req.form.email;
    res.json({ success: true });
    next();
});

module.exports = server.exports();

Request & Response Objects

Request (req)

req.querystring          // Query parameters: ?q=shoes -> req.querystring.q
req.form                 // Form POST data: req.form.email
req.httpMethod           // HTTP method: 'GET', 'POST', etc.
req.httpHeaders          // Request headers
req.currentCustomer      // Current customer object
req.locale               // Current locale
req.session              // Session object

Response (res)

res.render('template', model)   // Render ISML template with data
res.json(object)                // Return JSON response
res.redirect(url)               // Redirect to URL
res.setViewData(data)           // Add data to view model
res.getViewData()               // Get current view model
res.setStatusCode(code)         // Set HTTP status code
res.cacheExpiration(hours)      // Set cache duration

Middleware Chain

Each route is a series of functions with (req, res, next):

server.get('Show', 
    middleware1,
    middleware2,
    function (req, res, next) {
        // Main handler
        next();
    }
);

Critical: Always call next() to pass control, unless terminating the request.

Common Built-in Middleware

Controller Extension

Customize without modifying base code. Always import base first:

'use strict';
var server = require('server');
var page = module.superModule; // Get base controller
server.extend(page);

Extension Methods

Append Example (Most Common)

server.append('Show', function (req, res, next) {
    var viewData = res.getViewData();
    viewData.customData = 'My custom value';
    res.setViewData(viewData);
    next();
});

module.exports = server.exports();

Replace Example (State-Changing Actions)

// Use replace for payment, inventory updates, etc.
server.replace('Submit', function (req, res, next) {
    // Custom implementation
    res.json({ success: true });
    next();
});

Critical: Never use append for state-changing routes (payments, inventory). Use replace to prevent duplicate transactions.

CSRF Protection

var csrfProtection = require('*/cartridge/scripts/middleware/csrf');

// Display form - generates token automatically
server.get('ShowForm', csrfProtection.generateToken, function (req, res, next) {
    res.render('myForm', { pageTitle: 'Contact' });
    // pdict.csrf.tokenName and pdict.csrf.token auto-available
    next();
});

// Process form - validates token
server.post('Submit', csrfProtection.validateRequest, function (req, res, next) {
    // Token validated, safe to process
    next();
});

Important: Middleware automatically adds CSRF to pdict. Never manually add tokens to viewData.

Template usage:

<input type="hidden" name="${pdict.csrf.tokenName}" value="${pdict.csrf.token}"/>

Error Handling

server.get('Show', function (req, res, next) {
    try {
        var product = ProductMgr.getProduct(req.querystring.pid);
        
        if (!product) {
            res.setStatusCode(404);
            res.render('error/notfound');
            return next();
        }
        
        res.render('product/detail', { product: product });
    } catch (e) {
        Logger.error('Product error: ' + e.message);
        res.setStatusCode(500);
        res.render('error/general');
    }
    next();
});

Module Imports

// B2C Commerce APIs
var ProductMgr = require('dw/catalog/ProductMgr');
var Transaction = require('dw/system/Transaction');
var Logger = require('dw/system/Logger');
var URLUtils = require('dw/web/URLUtils');

// Cartridge modules (use */ for path resolution)
var collections = require('*/cartridge/scripts/util/collections');
var productHelper = require('*/cartridge/scripts/helpers/productHelpers');

Best Practice: Require modules inside route functions, not at file top.

URL Generation

var URLUtils = require('dw/web/URLUtils');

// Controller URL
var productUrl = URLUtils.url('Product-Show', 'pid', 'ABC123');

// HTTPS URL
var loginUrl = URLUtils.https('Login-Show');

// Static resource URL
var imageUrl = URLUtils.staticURL('/images/logo.png');

Route Events

Execute code at specific points in request lifecycle:

server.get('Show', function (req, res, next) {
    res.setViewData({ email: req.form.email });
    next();
});

// Execute after all middleware, before render
this.on('route:BeforeComplete', function (req, res) {
    var viewData = res.getViewData();
    // Modify view data if needed
});

JSON API Endpoints

server.get('GetCart', function (req, res, next) {
    var BasketMgr = require('dw/order/BasketMgr');
    var CartModel = require('*/cartridge/models/cart');
    
    var basket = BasketMgr.getCurrentBasket();
    var cart = new CartModel(basket);
    
    res.json(cart);
    next();
});

Complete Controller Example

'use strict';

var server = require('server');
var cache = require('*/cartridge/scripts/middleware/cache');
var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
var userLoggedIn = require('*/cartridge/scripts/middleware/userLoggedIn');

// Public page with caching
server.get('Show',
    cache.applyDefaultCache,
    function (req, res, next) {
        var ProductMgr = require('dw/catalog/ProductMgr');
        var product = ProductMgr.getProduct(req.querystring.pid);
        
        res.render('product/detail', { product: product });
        next();
    }
);

// Protected form display
server.get('EditProfile',
    server.middleware.https,
    userLoggedIn.validateLoggedIn,
    csrfProtection.generateToken,
    function (req, res, next) {
        res.render('account/editProfile');
        next();
    }
);

// Protected form submission
server.post('SaveProfile',
    server.middleware.https,
    userLoggedIn.validateLoggedIn,
    csrfProtection.validateRequest,
    function (req, res, next) {
        // Process form...
        res.json({ success: true });
        next();
    }
);

module.exports = server.exports();

Best Practices

1. Always call next() in middleware chain
2. Use ViewModels to prepare data for templates
3. Keep controllers thin - move logic to scripts/helpers
4. Use hooks for functionality that works for storefront and OCAPI
5. Handle errors gracefully - never expose stack traces
6. Use */cartridge/... for portable module paths
7. Lazy load modules - require inside functions, not at file top
8. Use page caching via middleware or res.cacheExpiration()

Related Skills

• sfcc-localization - Essential for localizing controller responses. Use Resource.msg() for all user-facing messages, error strings, and JSON responses. Never hardcode text in controllers.
• sfcc-logging - Comprehensive logging patterns including categories, custom log files, and log level checks for debugging controllers.

Detailed References

For comprehensive patterns and examples:

• Middleware Reference - Full middleware documentation
• Remote Includes - Remote include patterns
• Standard SFRA Controllers - Complete route reference

Converted and distributed by TomeVault — claim your Tome and manage your conversions.