Storage
Overview
The SCAYLE Storefront utilizes the Nitro Storage Layer, built on top of unstorage, to enable storage implementations that are runtime agnostic and can be connected to different data storages.
The Storefront expects two global storage mounts to be available:
storefront-cache: Used for global caching (e.g., for page caching withrouteRulesinnuxt.config.ts).storefront-session: Used for session storage.
storefront-cache is not related to the default cache mount point used by Nuxt and Nitro. The default cache mount point remains available as outlined in the Nitro Cache API documentation.
Configuration of Storage Mounts
Storage mounts can be configured through a server plugin. These server plugins are located in the ./server/plugins directory and are automatically registered by Nuxt.
Within a server plugin, the useStorage() composable can be utilized to mount an unstorage driver or any combination of unstorage drivers under a specific name. The SCAYLE Storefront requires storage mounts named storefront-session and storefront-cache. If these mounts are not explicitly provided, the system will default to using the in-memory storage driver.
The In-Memory driver is NOT recommended for production environments due to high memory consumption and potential data loss:
- In-memory data (such as user sessions) can be lost if the server runtime crashes (e.g.
node). - In-memory data may not be shared across multiple server runtime instances.
By default, the storefront-session and storefront-cache mounts are sufficient for the Storefront to function properly. However, to support different shops with specific storage settings, you can mount additional storage by appending the shopId (e.g., :shopId) to the end of the mount name.
Once configured, storefront-cache and storefront-session (and their shop-specific overrides) will handle caching and session management accordingly.
Using Runtime Configuration
You can utilize useRuntimeConfig() to access runtime configuration values when setting up storage mounts in a server plugin. This function allows you to dynamically configure storage options based on the environment, ensuring that your application can adapt to different settings without hardcoding sensitive information. By leveraging runtime configurations, you enhance the flexibility and maintainability of your application, allowing for seamless transitions between development, staging, and production environments.
Compression Support
The SCAYLE Storefront supports the use of any combination of drivers, allowing stored data to be compressed using the @scayle/unstorage-compression-driver.
The encoding option within the compressionDriver accepts a value of 'deflate', 'gzip', 'brotli', or 'none' to specify the compression algorithm used for the data of a specific storage mount.
Example: server/plugins/storageConfig.ts with Compression
import scayleKvDriver from '@scayle/unstorage-scayle-kv-driver'
import compressionDriver from "@scayle/unstorage-compression-driver"
export default defineNitroPlugin(() => {
const storage = useStorage()
// Configure global storage (used as base config for all shops)
storage.mount('storefront-session', compressionDriver({
encoding: 'brotli',
passthroughDriver: scayleKvDriver({}),
}))
storage.mount('storefront-cache', compressionDriver({
encoding: 'brotli',
passthroughDriver: scayleKvDriver({}),
}))
})
Since @scayle/unstorage-compression-driver currently offers limited configuration options, it is not possible to pass dedicated options to the selected compression encoding function of Node.js zlib. This means the compression currently uses the default zlib options.
After changing the compression option, it is recommended to empty the corresponding storage instance/database (e.g., your SCAYLE KV instance) to prevent data decompression failures due to an incorrect algorithm being used on legacy data.
SCAYLE KV Driver
The SCAYLE KV driver is a custom unstorage driver designed to streamline the setup of the Storefront's storage.
By default, the following storage configuration is commonly used to store cache and session entries with SCAYLE KV:
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 in your .env file:
For single-instance Valkey/Redis setups, disableClusterMode must be set to true in the driver configuration. You can dynamically overwrite this option, for instance, only during local development, by using import.meta.dev.
Configuration of Storage Mounts Through the Nitro Configuration
Nuxt/Nitro also allows the creation of additional storage mount points directly via the nuxt.config.ts file. For detailed instructions on configuring mount points using Nitro config, please refer to the official documentation.
The nitro.storage option configures storage mounts during the build process. Consequently, these mounts cannot be modified at runtime.
