Configuration

Overview

The SCAYLE Storefront Application provides configuration options for Storefront API and OAuth authentication, storage, sessions, multi-shop support, and other features.

Configuration splits into two categories:

Build-time configuration: Options defined in nuxt.config.ts under the storefront key and build-time environment variables that are processed during the build phase and cannot be changed at runtime
Runtime configuration: Options defined in nuxt.config.ts under runtimeConfig.storefront that can be overridden at runtime using environment variables

Runtime configuration further divides into:

Private runtime configuration: Server-side only configuration (e.g., API tokens, secrets)
Public runtime configuration: Client-accessible configuration (e.g., logging settings)

Build-time configuration options are processed during the build phase and cannot be changed at runtime. These include options defined in nuxt.config.ts under the storefront key and build-time environment variables.

Module Options

Module options are defined in nuxt.config.ts under the storefront key.

Custom RPC Methods

Custom RPC methods can be added to the Storefront Application. The names of these RPC methods should be provided in rpcMethodNames, and their directory should be specified in rpcDir.

For more details on RPC methods, including how to create custom RPC methods and use them in your application, see the RPC Methods documentation.

API Base Path

By default, all API routes will be nested under /api. This can be changed via the apiBasePath configuration in the build-time storefront configuration.

Important: If you modify the apiBasePath value, you must also update the routeRules configuration in nuxt.config.ts to ensure API routes are not cached. The routeRules should include a pattern matching your custom API base path (e.g., /custom-api/**) with caching disabled to prevent issues with session-related RPC calls and potentially failing requests.

Build-Time Environment Variables

The Storefront Application can be configured using build-time environment variables. These are typically used to enable opting out of certain features or to exclude unnecessary code and dependencies during the compilation process.

To use these variables, ensure they are set when running nuxt build.

SFC_OMIT_MD5: MD5 is supported as a hash algorithm for historical and backward-compatibility reasons, but SHA256 is now preferred. If you do not need to use MD5 in your application, you can set this variable to true to remove the MD5-supporting code and dependencies from your build.
SFC_OMIT_COMPRESSION: If set to true, compression driver support will be excluded from the build, reducing bundle size if compression is not needed.
SFC_PLUGIN_CONFIG_VALIDATION_ENABLED: Controls whether runtime configuration validation is enabled at startup. Set to false to disable validation (not recommended for production).
SFC_PLUGIN_DOMAIN_CONFIG_VALIDATION_ENABLED: Controls whether domain configuration validation is enabled for domain-based shop selection. Set to false to disable validation (not recommended for production).
SFC_PLUGIN_POWERED_BY_ENABLED: Controls whether the X-Powered-By HTTP header is set. Set to false to disable the header.
SFC_PLUGIN_RUNTIME_PERFORMANCE_ENABLED: Controls whether runtime config caching is enabled for performance optimization. Set to false to disable caching.

Configuration Validation

The Storefront Application validates all runtime configuration at startup using Zod schemas. If validation fails, the application will log detailed error messages and throw an error.

Validation is enabled by default and can be disabled by setting:

For domain-based shop selection, domain configuration validation is also performed. This can be disabled by setting:

Runtime Configuration

Runtime configuration options are defined in nuxt.config.ts under runtimeConfig.storefront (private) and runtimeConfig.public.storefront (public). These options can be overridden at runtime using environment variables.

Some parts of the Storefront Application configuration can and should be specified through runtime environment variables. This practice offers several benefits:

Security: Confidential information, such as API tokens, should not be checked into source repositories or included in compiled assets. Instead, these values should be saved in a secure location and loaded at runtime.
"Build once, deploy anywhere": This DevOps best practice allows you to build your application once and promote the same release through different environments. Runtime configuration eliminates inconsistencies between environments (e.g., production vs. staging domains).
Local Development: Local development environments often differ significantly from live environments (e.g., local HTTPS setup vs. Nginx, in-memory cache vs. Redis). Controlling these overrides in a .env file that is not checked into version control is crucial (see local .env.example as reference).

Private Runtime Configuration

Private runtime configuration is server-side only and should never be exposed to the client. Use this for sensitive data like API tokens and secrets.

Storefront API Configuration

This section sets up the connection details for the Storefront API by defining sapi.host and sapi.token. Previously, the Storefront API was known as the Backbone API and abbreviated as BAPI. You may encounter both terms in your existing projects code and documentation, but they refer to the same service.

The host and token field should be kept as an empty string in your nuxt.config.ts and replaced at runtime with the proper token via an environment variable.

OAuth Configuration

The oauth configuration provides Token-based (OAuth) authentication settings required for user authentication and authorization. This includes the OAuth API host, client ID, and client secret.

For more details on OAuth configuration and authentication, see the Login and Registration documentation.

Session Configuration

The behavior of the session handling logic within the Storefront Application can be controlled through the session configuration property.

For more details on session configuration, including session management, app keys, and identity provider configuration, see the Sessions documentation.

App Keys Configuration

App keys are used to generate user-specific identifiers for baskets and wishlists. The configuration format for AppKey generation can be customized. Baskets and wishlists are unscoped and shared across all configured shops by default. If baskets and wishlists should be scoped by country shop, the respective keys need to be extended with {shopId}.

For more details on app keys, including how they work and when to customize them, see the Sessions documentation.

Shop Selector Configuration

The shopSelector configuration determines how the application identifies and switches between different country shops. It influences how the domain and path properties are used within the shops configuration.

Available modes include:

domain: Shop selection based on the request domain. Each country shop must have a unique domain configured.
path: Shop selection based on the URL path prefix. Each country shop must have a path configured (e.g., /en, /de).
path_or_default: Similar to path, but the default shop can be accessed without a path prefix.

For more details on shop selector configuration and routing options, see the Internationalization documentation.

Redirects Configuration

The redirects configuration controls how the application handles URL redirects by leveraging the Storefront API, which is synchronized with the SCAYLE Panel. When enabled, the Storefront Core intercepts requests and checks for potential redirects via the Storefront API. If a match is found, a 30x HTTP response is returned with the target in the Location header and the appropriate status code.

The Redirects Guide explains in detail how to manage redirects in the Storefront Application, including details on managing redirects directly in the SCAYLE Panel (e.g., create absolute or relative redirects, delete or export redirects). See the Redirects documentation.

Identity Provider (IDP) Configuration

Identity Provider support for Token-based (OAuth) Authentication can be configured globally or per-country shop.

For more details on configuring identity providers, including country shop-specific configuration, see the Sessions documentation.

Cache Configuration

The cache configuration controls internal cache behavior within the Storefront Application. This includes enabling or disabling cache and providing authentication credentials when required.

For details on the cache configuration options, including authentication and enabling/disabling, refer to the Caching documentation.

Public Shop Data Configuration

The publicShopData configuration allows you to expose additional server-side context properties to the client-side. These properties from shop configuration become available on the client via $currentShop and $availableShops.

It's also possible to define additional custom properties within shop configurations. This is useful if you'd like to include extra metadata that is specific to a particular country shop (e.g., countryCode, paymentProviders). To properly type these extended shop configurations for TypeScript, augment the AdditionalShopConfig interface (from @scayle/storefront-nuxt).

With Parameters (withParams)

Many Storefront API endpoints support the with parameter that allows for requesting additional attributes from an entity. While this parameter can be set whenever using a relevant RPC composable (such as useProduct or useWishlist), default values can also be set in the module configuration, serving as a fallback.

Default withParams can be set for: basket, wishlist, product, productCategory, category, search, and variant. Previous withParams keys are overridable using prefix NUXT_PUBLIC_WITH_PARAMS_.

Legacy: enableSessionMigration

The legacy configuration provides feature flags for legacy features and migration scenarios.

Legacy configuration options are intended for migration scenarios and should not be modified unless you are upgrading from an older version or have specific requirements. Changing these options can affect application behavior and may cause unexpected issues.

enableSessionMigrationnables automatic migration of legacy session cookies to the new session format. Starting with`` ``@scayle/[email protected], the Storefront Application uses unique session cookie names for each shop (e.g., $session-1001) instead of a single $session cookie with path-based routing.

When to enable: Only set to true when upgrading from a version prior to @scayle/[email protected] to prevent loss of user sessions. Keep enabled in production for a period exceeding your configured session TTL (default: 4 weeks) to ensure all legacy sessions are migrated, then disable.
Default: false

Storage Configuration

The Storefront Application uses the Nitro Caching System, built on top of Unstorage and the Nitro Storage Layer, to provide pre-configured and reusable storage mount points. These are used internally by the Storefront Application & underlying SDKs to enable various caching abilities.

The storage option within storefront runtime configuration is deprecated. Consider using Nuxt storage configuration instead.

For more details on storage configuration, including driver options, advanced settings, and migration from the deprecated configuration, see the Storage documentation.

Public Runtime Configuration

Public runtime configuration is accessible on both server and client. Use this for non-sensitive configuration like logging settings or anything that can safely be exposed to the client.

Logging

The log section controls the behavior of the Storefront SDKs' logging functionality. The name property controls how log messages are prefixed (e.g., [my-store] Storefront SDK is loaded!). The level property controls the verbosity of the log output (e.g., debug, info, warn, error).

RPC Default Lazy Loading

Examples:

Legacy: enableDefaultGetCachedDataOverride

The public legacy configuration provides feature flags for legacy features and migration scenarios.

enableDefaultGetCachedDataOverride controls whether useRpc composable uses data isolation between calls or shared cached data. When enabled, each useRpc call uses its own cached data instead of sharing data across calls with the same key.

When to enable: Only set to true if you need data isolation between useRpc calls. The default behavior (shared cached data) is recommended for most use cases.
Migration note: This option replaced the previous disableDefaultGetCachedDataOverride option with reversed logic. If you were using disableDefaultGetCachedDataOverride: true, set enableDefaultGetCachedDataOverride: false to maintain the same behavior.
Default: false (or undefined)

Country Shop-Specific Configuration

A key aspect of the SCAYLE ecosystem is its ability to support multiple country shops. The configuration for these different country shops, including their shopId, locale, and currency, can be managed in the config/shops.ts file. This allows you to define and customize settings specific to each shop instance.

Each country shop in your Storefront Application can have its own configuration. Country shop configurations are defined under runtimeConfig.storefront.shops and are indexed by shop ID.

For a more detailed explanation of how to configure shops and all available options, please refer to our in-depth documentation on Shop Configuration.

Password Reset URL

The password reset URL is country shop-specific and is configured under the auth property within a country shop's configuration. It is required to contain {hash}, which is replaced by the Storefront SDKs with the actual hash for password reset.

Additional Shop Data

It's also possible to define additional custom properties within country shop configurations. This is useful if you'd like to include extra metadata that is specific to a particular country shop (e.g., cookieBanner, paymentProviders). The extra properties can then be accessed from the country shop.

To properly type these extended country shop configurations for TypeScript, augment the AdditionalShopConfig interface (from @scayle/storefront-nuxt).

Image Base URL (Deprecated)

The imageBaseUrl configuration option is no longer supported and has no effect. The Storefront Application now sets image.providers.default.options.baseURL of the Nuxt Image module by default within nuxt.config.ts.

NUXT_STOREFRONT_ Environment Variables

Most of the @scayle/storefront-nuxt module settings can be configured at runtime using environment variables that match a specific format. They should begin with NUXT_STOREFRONT_ and be followed by an upper-snake-case version of the property name.

Nuxt automatically converts environment variables to runtime configuration following these rules:

Private config: Use NUXT_ prefix
Public config: Use NUXT_PUBLIC_ prefix
Nested properties: Use underscores to separate levels (e.g., NUXT_STOREFRONT_SESSION_SAME_SITE)
Shop-specific config: Use NUXT_STOREFRONT_SHOPS_{UNIQUE_IDENTIFIER}_{PROPERTY} where {UNIQUE_IDENTIFIER} is the shop ID or locale

Deeply nested configuration values are also supported. For example, setting a shop domain for a specific shop on staging uses the shop ID as the key in the configuration shops object.

You can learn more about how the Nuxt runtimeConfig works in the Runtime Config Guide.

Use environment variables for sensitive data: Never commit API tokens, secrets, or passwords to version control. Use environment variables or secure secret management systems.
Use build-time config for static options: Use storefront build-time configuration for options that don't change between environments (e.g., RPC method names).
Use runtime config for environment-specific values: Use runtimeConfig for values that differ between development, staging, and production environments.

Country Shop Configuration

Use shop ID as unique identifier: When configuring country shop-specific overrides, use the shop ID as the {UNIQUE_IDENTIFIER} in environment variable names. This avoids conflicts when multiple country shops share the same locale.
Set default shop: Mark one country shop as isDefault: true to ensure proper fallback behavior.
Configure shop-specific checkout: Each country shop requires to have its own checkout configuration if using different checkout instances.

Security

Keep secrets private: Never expose private runtime configuration to the client. Only use runtimeConfig.public for non-sensitive configuration.
Validate configuration: Keep configuration validation enabled in production to catch misconfigurations early.

Performance

Optimize withParams: Configure withParams to request only the data you need. Over-requesting data increases API response times and payload sizes.
Use appropriate cache settings: Configure cache settings based on how current your data needs to be and infrastructure capabilities.

Environment variable name doesn't match Nuxt's naming convention
Environment variable is not available at runtime
Configuration is defined in the wrong section (build-time vs runtime)

Solution

Verify the environment variable name follows the NUXT_ or NUXT_PUBLIC_ prefix pattern
Check that the environment variable is set in your deployment environment
Ensure the configuration option is in runtimeConfig (not build-time config) if you want to override it

Missing required configuration options
Invalid value types (e.g., string instead of number)
Invalid enum values

Solution

Review the validation error messages for specific field issues
Check that all required fields are provided
Verify value types match the expected schema (see configuration documentation above)

shopSelector mode doesn't match shop configuration (e.g., using domain mode but shops only have path configured)
Domain or path values don't match actual request URLs
i18n configuration doesn't match shop selector mode

Solution

Verify shopSelector matches your routing strategy (domain or path)
Ensure all shops have the appropriate domain or path configured
Check that i18n configuration aligns with shop selector mode
Enable domain validation to catch configuration mismatches

Prevention

Use the domain validation plugin to catch configuration issues at startup.