Configuration

Overview

Comprehensive configuration is crucial for unlocking the full potential of your SCAYLE Storefront Application, allowing you to tailor its behavior precisely to specific business needs and integrate it seamlessly with the broader SCAYLE ecosystem. By leveraging settings across various files and tools, you can fine-tune essential aspects like API connections, storage, sessions, multi-shop support, and various features.

Module Configuration

The core behavior of your SCAYLE Storefront Application can be easily configured through its main Nuxt module (@scayle/storefront-nuxt).

Storefront API

This section sets up the connection details for the Storefront API by defining sapi.host and sapi.token.

ts

Copy

The 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. See the Runtime Configuration section for more details.

Storage

The Storefront SDKs utilize the powerful 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 SDKs to enable various caching abilities.

For more details on storage configuration, including driver options and advanced settings, check the Storage Guide.

ts

Copy

Sessions

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

Find out more about Sessions.

Shops

A key aspect of the SCAYLE ecosystem is its ability to support multiple shops. The configuration for these different 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.

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 shop-specific and is configured under the auth property within a shop's configuration. It is required to contain {hash}, which is replaced by the Storefront SDKs with the actual hash for password reset.

typescript

Copy

Additional Shop Data

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 shop (e.g., cookieBanner, paymentProviders).

typescript

Copy

The extra properties can then be accessed from the shop.

html

Copy

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

typescript

Copy

Public Shop Data

If you want these additional properties to be accessible on the client-side, they must also be explicitly added to the publicShopData configuration array. Otherwise, they will only be accessible in server-side contexts (such as RPC methods).

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.

Logging

The log section controls the behavior of the Storefront SDKs' logging functionality.

typescript

Copy

• name Controls how log messages are prefixed (e.g., [my-store] Storefront SDK is loaded!).
• level: Controls the verbosity of the log output (e.g., debug, info, warn, error).

Optional Configs

The following sections provide optional configurations that are not strictly required for basic application functionality but offer extended control.

API Base URL

By default, all API routes will be nested under /api (or /[prefix]/api for shops with path-based switching). This can be changed via the apiBaseUrl configuration. The prefix is automatically added for shops with path-based switching and should not be set manually in this configuration. This setting can also be overridden at the shop level.

typescript

Copy

Cache

typescript

Copy

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

Redirects

The redirects section allows for managing redirects within the Storefront Application.

typescript

Copy

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).

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.

typescript

Copy

Custom RPC Methods

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

typescript

Copy

Find out more about RPC Methods.

Runtime Configuration

Some parts of the Storefront SDKs' 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.

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. The module automatically configures runtimeConfig to simplify this process for developers.

For example, setting the global Redis configuration might look like this:

env

Copy

Deeply nested configuration values are also supported. For example, setting a shop domain for a specific shop on staging:

env

Copy

The number in the middle (1001, 1002, 1003) is the shopId which is used as the key in the configuration's shops object.

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

.env Files

Runtimes including Node versions 20.6.0 or later, Deno, and Bun support loading environment variables from a .env file. This is recommended as the easiest approach for loading runtime configurations in your applications. For more information, see the Deployment Guide.

Build Configuration

Lastly, the Storefront SDKs 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. The nuxt build command automatically loads the .env file if present, which is one way to provide these variables.

Supported Build-Time Environment Variables

• 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.