Storage
Introduction
SCAYLE Storefront utilizes the Nitro Storage Layer, built on top of unstorage, to provide pre-configured storage implementations that are runtime agnostic and can be configured to use different data storages.
Storefront provides two global default storage options:
storefront-cache(for global caching, e.g. for page caching with routeRules innuxt.config.ts)storefront-session(for session storage)
The storage configurations for the respective pre-configured storage mount points are based on storefront.storage.cache and storefront.storage.session keys. This unifies their usage across Storefront applications and allows deeper integration with the underlying Storefront SDKs.
storefront-cache is not related to the default cache mount point used by Nuxt and Nitro. The cache mount point remains available as outlined in the Nitro Cache API documentation.
Configuration of Storage Drivers through storefront.storage
Storefront uses an abstract-type StorageConfig interface with the following structure:
interface StorageConfig {
cache?: StorageEntity
session?: StorageEntity
}
Both cache and session are optional. If not explicitly configured, Storefront defaults to using an In-Memory storage driver for both.
- The In-Memory driver is NOT recommended for production due to high memory consumption and potential memory leaks.
- Cached data (such as user sessions) can be lost if the server runtime crashes (e.g.
node). - Cached data may not be shared across multiple server runtime instances.
The driver configuration for storefront.storage.cache or storefront.storage.session determines which of the supported unstorage driver will be used. Configuration options vary depending on the selected driver. For details, refer to the respective unstorage Driver documentation.
Once configured, storefront-cache and storefront-session will handle caching and session management accordingly.
Compression Support
Storefront storage supports data compression via the compression key. When enabled, @scayle/storefront-nuxt automatically wraps the configured storage driver with @scayle/unstorage-compression-driver.
The optional compression key accepts a value of deflate, gzip, brotli or none to specify the encoding algorithm used to compress all data of a specific storage. After setting a compression option, it is recommended to empty the corresponding storage instance/database, e.g., Redis.
Since @scayle/unstorage-compression-driver only offers limited configuration options, it is currently not possible to pass dedicated options to the selected compression encoding function of node:zlib. This means that the compression is currently using the default options of the Node.js runtime.
After changing the compression option, it is recommended to empty the corresponding storage instance/database, e.g. scayleKv.Without this, decompression of legacy data will fail due to the use of an incorrect decompression algorithm.
SCAYLE KV Driver
The SCAYLE KV driver is a custom unstorage driver intended to streamline the setup of Storefront.
By default, the following storage configuration is used to store cache and session entries with SCAYLE KV:
runtimeConfig: {
storefront: {
storage: {
cache: {
driver: 'scayleKv',
compression: 'brotli',
// Default TTL of 10 minutes for the cache.
// This is required so that the SSR cache also expires at some point.
ttl: 10 * 60,
disableClusterMode: false, // Overwrite: NUXT_STOREFRONT_STORAGE_CACHE_DISABLE_CLUSTER_MODE
},
session: {
driver: 'scayleKv',
disableClusterMode: false, // Overwrite: NUXT_STOREFRONT_STORAGE_SESSION_DISABLE_CLUSTER_MODE
}
}
}
}
Running SCAYLE KV Locally
SCAYLE KV can run independently during local development. To set it up, a Valkey/Redis instance or cluster is required, along with the following environment variables:
SCAYLE_KV_HOST= # is used to set the host location (defaults to localhost)
SCAYLE_KV_PORT= # is used to set the host port (defaults to 6379)
SCAYLE_KV_USER= # is used as username for authenticating against the KV instance
SCAYLE_KV_PASSWORD= # is used as password for authenticating against the KV instance
SCAYLE_KV_TLS= # set to true if TLS should be enabled
SCAYLE_KV_BASE= # global prefix used to generate cache keys
For single-instance Valkey/Redis setups, disableClusterMode must be set to true. If you want to overwrite this option, e.g. during local development, you can use the NUXT_STOREFRONT_STORAGE_CACHE_DISABLE_CLUSTER_MODE and NUXT_STOREFRONT_STORAGE_SESSION_DISABLE_CLUSTER_MODE environment variable to overwrite the disableClusterMode option within nuxt.config.ts without changing the config file itself.
NUXT_STOREFRONT_STORAGE_CACHE_DISABLE_CLUSTER_MODE=true
NUXT_STOREFRONT_STORAGE_SESSION_DISABLE_CLUSTER_MODE=true
Using other providers
The storefront.storage.cache and storefront.storage.session configurations align with Nitro StoragMounts Interface, ensuring compatibility with Nuxt's global nitro.storage options.
Any built-in unstorage driver can be used. For a full list, see the Unstorage Documentation.
Example: Using Redis as Storage Driver
runtimeConfig: {
storefront: {
storage: {
cache: {
// Redis Options: https://redis.github.io/ioredis/index.html#RedisOptions
driver: 'redis',
compression: 'brotli',
host: 'localhost',
port: 6379,
username: '',
password: '',
tls: false,
ttl: 10 * 60,
checkServerIdentity: undefined,
maxRetriesPerRequest: 1,
},
session: {
driver: 'redis',
compression: 'brotli',
host: 'localhost',
port: 6379,
username: '',
password: '',
tls: false,
ttl: 10 * 60,
checkServerIdentity: undefined,
maxRetriesPerRequest: 1,
}
}
}
}
Configuration of Storage Drivers through the nitro configuration
In addition to the storage mounts created by Storefront, Nuxt/Nitro also allows the creation of additional mount points via the nuxt.config.ts file. For detailed instructions on configuring mount points using Nitro config, please refer to the official documentation.
