b2c-custom-caches

B2C Custom Caches Custom caches improve code performance by storing data that is expensive to calculate, takes a long time to retrieve, or is accessed frequently. Caches are defined in JSON files within cartridges and accessed via the Script API. When to Use Custom Caches Use Case Example Expensive calculations Check if any variation product is on sale for base product display External system responses Cache in-store availability or prices from external APIs Configuration settings Store configuration data from JSON files or external sources Frequently accessed data Product attributes, category data, site preferences Limitations Constraint Value Total memory per app server ~20 MB for all custom caches Max caches per code version 100 Max entry size 128 KB Supported value types Primitives, arrays, plain objects, null (not undefined ) Cross-server sync None (caches are per-application-server) Defining a Custom Cache File Structure my_cartridge/ ├── package.json # References caches.json └── caches.json # Cache definitions package.json Add a caches entry pointing to the cache definition file: { "name" : "my_cartridge" , "caches" : "./caches.json" } caches.json Define caches with unique IDs and optional expiration: { "caches" : [ { "id" : "ProductAttributeCache" } , { "id" : "ExternalPriceCache" , "expireAfterSeconds" : 300 } , { "id" : "SiteConfigCache" , "expireAfterSeconds" : 60 } ] } Property Required Description id Yes Unique ID across all cartridges in code version expireAfterSeconds No Maximum seconds an entry is retained Using Custom Caches Script API Classes Class Description dw.system.CacheMgr Entry point for accessing defined caches dw.system.Cache Cache instance for storing and retrieving entries Basic Usage var CacheMgr = require ( 'dw/system/CacheMgr' ) ; // Get a defined cache var cache = CacheMgr . getCache ( 'ProductAttributeCache' ) ; // Get value (returns undefined if not found) var value = cache . get ( 'myKey' ) ; // Store value directly cache . put ( 'myKey' , { data : 'value' } ) ; // Remove entry cache . invalidate ( 'myKey' ) ; Recommended Pattern: get with Loader Use get(key, loader) to automatically populate the cache on miss: var CacheMgr = require ( 'dw/system/CacheMgr' ) ; var Site = require ( 'dw/system/Site' ) ; var cache = CacheMgr . getCache ( 'SiteConfigCache' ) ; // Loader function called only on cache miss var config = cache . get ( Site . current . ID + 'config' , function ( ) { // Expensive operation - only runs if not cached return loadConfigurationFromFile ( Site . current ) ; } ) ; Scoped Cache Keys Include scope identifiers in keys to separate entries by context: var CacheMgr = require ( 'dw/system/CacheMgr' ) ; var Site = require ( 'dw/system/Site' ) ; var cache = CacheMgr . getCache ( 'ProductCache' ) ; // Site-scoped key var siteKey = Site . current . ID + '' + productID ; var productData = cache . get ( siteKey , loadProductData ) ; // Catalog-scoped key var catalogKey = 'catalog_' + catalogID + '' + productID ; var catalogData = cache . get ( catalogKey , loadCatalogData ) ; // Locale-scoped key var localeKey = request . locale + '' + contentID ; var content = cache . get ( localeKey , loadLocalizedContent ) ; Cache Methods Method Description get(key) Returns cached value or undefined get(key, loader) Returns cached value or calls loader, stores result put(key, value) Stores value directly (overwrites existing) invalidate(key) Removes entry for key Best Practices Do Use get(key, loader) pattern for automatic population Include scope (site, catalog, locale) in cache keys Set appropriate expireAfterSeconds for time-sensitive data Handle cache misses gracefully (data may be evicted anytime) Use descriptive cache IDs Don't Include personal user data in cache keys (keys may appear in logs) Store Script API objects (only primitives and plain objects) Rely on cache entries existing (no persistence guarantee) Expect cross-server cache synchronization Store undefined values (use null instead) Cache Invalidation Caches are automatically cleared when: Any file in the active code version changes A new code version is activated Data replication completes Code replication completes Manual invalidation only affects the current application server: var cache = CacheMgr . getCache ( 'MyCache' ) ; // Invalidate single entry (current app server only) cache . invalidate ( 'myKey' ) ; // Storing undefined has same effect as invalidate cache . put ( 'myKey' , undefined ) ; Common Patterns Caching External API Responses var CacheMgr = require ( 'dw/system/CacheMgr' ) ; var LocalServiceRegistry = require ( 'dw/svc/LocalServiceRegistry' ) ; var priceCache = CacheMgr . getCache ( 'ExternalPriceCache' ) ; function getExternalPrice ( productID ) { return priceCache . get ( 'price_' + productID , function ( ) { var service = LocalServiceRegistry . createService ( 'PriceService' , { createRequest : function ( svc , args ) { svc . setRequestMethod ( 'GET' ) ; svc . addParam ( 'productId' , args . productID ) ; return null ; } , parseResponse : function ( svc , response ) { return JSON . parse ( response . text ) ; } } ) ; var result = service . call ( { productID : productID } ) ; return result . ok ? result . object : null ; } ) ; } Caching Expensive Calculations var CacheMgr = require ( 'dw/system/CacheMgr' ) ; var saleCache = CacheMgr . getCache ( 'ProductSaleCache' ) ; function isProductOnSale ( masterProduct ) { return saleCache . get ( 'sale_' + masterProduct . ID , function ( ) { var variants = masterProduct . variants . iterator ( ) ; while ( variants . hasNext ( ) ) { var variant = variants . next ( ) ; if ( isInPromotion ( variant ) ) { return true ; } } return false ; } ) ; } Configuration Cache with Site Scope var CacheMgr = require ( 'dw/system/CacheMgr' ) ; var Site = require ( 'dw/system/Site' ) ; var File = require ( 'dw/io/File' ) ; var FileReader = require ( 'dw/io/FileReader' ) ; var configCache = CacheMgr . getCache ( 'SiteConfigCache' ) ; function getSiteConfig ( ) { var siteID = Site . current . ID ; return configCache . get ( siteID + '_config' , function ( ) { var configFile = new File ( File . IMPEX + '/src/config/' + siteID + '.json' ) ; if ( ! configFile . exists ( ) ) { return null ; } var reader = new FileReader ( configFile ) ; var content = reader . getString ( ) ; reader . close ( ) ; return JSON . parse ( content ) ; } ) ; } Troubleshooting Issue Cause Solution Cache not found exception Cache ID not defined in any caches.json Add cache definition to caches.json Duplicate cache ID error Same ID used in multiple cartridges Use unique IDs across all cartridges Entry not stored Value exceeds 128 KB limit Reduce data size or cache subsets Entry not stored Value contains Script API objects Use only primitives and plain objects Unexpected cache misses Different app server or cache cleared Always handle misses gracefully Check the custom error log and custom warn log for cache-related messages.