docs
  1. SCAYLE Resource Center
  2. Developer Guide
  3. Basic Setup
  4. Introduction

Introduction

Module Configuration

The behavior of the Storefront Core Nuxt module can be configured through the module configuration in nuxt.config.ts.

This guide will walk through the most critical sections of the configuration.

Storefront API

First, we'll set up the configuration for the Storefront API. This is done by setting sapi.host and sapi.token.

Previously, the Storefront API was known as the Backbone API and subsequently abbreviated as BAPI. You may encounter both terms in our code and documentation, but they refer to the same service.

let config = {
    sapi: {
      host: 'https://{{tenant-space}}.storefront.api.scayle.cloud/v1/',
      token: '',
   }
}

The token field should be kept as an empty string and replaced at runtime with the proper token via an environment variable. See Runtime Configuration.

Storage

Storefront Core uses the powerful Nitro - Caching System, built on top of unstorage and the Nitro - Storage Layer, to provide pre-configured and reusable mountpoints. These are used internally by Storefront Core to enable different caching abilities.

For more details check Caching.

let config = {
    storage: {
        cache: {
            driver: 'redis',
            compression: 'gzip',
            host: 'localhost',
            port: 6379,
        },
        session: {
            driver: 'redis'.
            compression: 'none',
            host: 'localhost',
            port: 6379,
            db: 1,
        },
    }
}

Sessions

The behavior of the session handling logic can be controlled through the sessions configuration property.

Find out more about sessions.md.

Shops

Storefront applications typically support multiple shops for different regions or languages. In the shops configuration you can specify which shops to use from your SCAYLE instance.

The configuration is an object keyed by shopId. Each shop configuration should specify a shopId, locale and currency.

let config = {
    shops: {
        1001: {
            shopId: 1001,
            locale: 'en-US',
            currency: 'USD',
        },
        1002: {
            shopId: 1002,
            locale: 'de-DE',
            currency: 'EUR',
        },
        1003: {
            shopId: 1003,
            locale: 'de-AT',
            currency: 'EUR',
        }
    }
}

Shop Overrides

It's also possible to override the sapi, storage, appKeys, session and checkout options at the shop level. Storefront Core will first attempt to use the settings defined on the current shop, falling back to the top-level configurations if necessary.

Path and Domain

domain and path can also be set on the shop configuration. How you configure this depends on if your application is using path-based or domain-based shop switching. With domain-based switching, your shops would have base URLs like en.example.com, de.example.com and at.example.com (or example.com, example.de and example.at) whereas with path-based switching, the base URLs would look something like example.com/en, example.com/de, and example.com/at.

If you are using path-based switching, set the domain for each shop to identical values. path should be set to the path prefix you wish to use for each shop. It can be the same as the shop's locale code, but that is not a requirement.

let config = {
    shopSelector: 'path',
    shops: {
        1001: {
            shopId: 1001,
            locale: 'en-US',
            currency: 'USD',
            domain: 'example.com',
            path: 'en',
        },
        1002: {
            shopId: 1002,
            locale: 'de-DE',
            currency: 'EUR',
            domain: 'example.com',
            path: 'de',
        },
        1003: {
            shopId: 1003,
            locale: 'de-AT',
            currency: 'EUR',
            domain: 'example.com',
            path: 'at',
        }
    }
}

If you are using domain-based switching, set the domain for each shop to a unique value. path can be ignored.

let config = {
    shopSelector: 'domain',
    shops: {
        1001: {
            shopId: 1001,
            locale: 'en-US',
            currency: 'USD',
            domain: 'example.com',
        },
        1002: {
            shopId: 1002,
            locale: 'de-DE',
            currency: 'EUR',
            domain: 'example.de',
        },
        1003: {
            shopId: 1003,
            locale: 'de-AT',
            currency: 'EUR',
            domain: 'example.at',
        }
    }
}

Password reset URL

The password reset URL is also shop-specific and is configured under the auth property. It is required to contain {hash} which is replaced by Storefront Core with the actual hash.

let config = {
    shops: {
        1001: {
            shopId: 1001,
            locale: 'en-US',
            currency: 'USD',
            auth: {
                resetPasswordUrl: 'http://localhost:3000/signin?hash={hash}',
            },
        },
        1002: {
            shopId: 1002,
            locale: 'de-DE',
            currency: 'EUR',
            auth: {
                resetPasswordUrl: 'http://localhost:3000/signin?hash={hash}',
            },
        },
        1003: {
            shopId: 1003,
            locale: 'de-AT',
            currency: 'EUR',
            auth: {
                resetPasswordUrl: 'http://localhost:3000/signin?hash={hash}',
            },
        }
    }
}

Additional Shop Data

It's also possible to define additional properties to shop configurations. This is useful if you'd like to have extra metadata that is shop-specific.

let config = {
    shops: {
        1001: {
            shopId: 1001,
            locale: 'en-US',
            currency: 'USD',
            cookieBanner: false,
            paymentProviders: ['visa', 'mastercard', 'paypal']
        },
        1002: {
            shopId: 1002,
            locale: 'de-DE',
            currency: 'EUR',
            cookieBanner: true,
            paymentProviders: ['paypal', 'klarna', 'SEPA'],
        },
        1003: {
            shopId: 1003,
            locale: 'de-AT',
            currency: 'EUR',
            cookieBanner: true,
            paymentProviders: ['paypal', 'klarna', 'SEPA'],
        }
    },
    publicShopData: ['cookieBanner', 'paymentProviders']
}

The extra properties can then be accessed from the shop.

<script setup>
    const { cookieBanner } = useCurrentShop()
    if (cookieBanner) {
        confirm('Want cookies?')
    }
</script>

To properly type the extended shop config, augment the AdditionalShopConfig interface.

declare module '@scayle/storefront-nuxt' {
    export interface AdditionalShopConfig {
        cookieBanner: boolean,
        paymentProviders: string[]
    }
}

Public Shop Data

If you want the additional properties to be exposed to the client, they should also be added to the publicShopData config. Otherwise, they will only be accessible in server-side contexts such as RPC methods.

Image Base URL

The imageBaseUrl is no longer supported and has no effect. The Storefront Boilerplate sets image.providers.default.options.baseURL of the nuxt/image module by default within the nuxt.config.ts. Please check nuxt/image documentation for more details.

Log

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

let config = {
    log: {
        name: 'my-store',
        level: 'debug',
    }
}
  • name controls how log messages are prefixed
  • level controls the verbosity of the log output
[my-store] Storefront Core is loaded!

Optional Configs

The following sections are not required to be defined.

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 in the config. It can also be overridden at the shop level.

let config = {
    apiBaseUrl: '/my-api',
}

Cache

let config = {
    cache: {
        auth: {
            username: '',
            password: '',
        },
        enabled: true
    }
}

Find out more about Caching.

Redirects

let config = {
    redirects: {
        enabled: true,
        queryParamWhitelist: [],
    }
}

Redirects section explains in detail managing redirects in the Storefront Boilerplate.
You can also manage Redirects in the SCAYLE Panel (Create absolute or relative redirects, delete or export redirects).

With Parameters

Many Storefront API endpoints support with parameter that allows for requesting additional attributes from the entity. The with parameter can be set whenever using a relevant RPC composable such as useProduct or useWishlist, but default values of this parameter can also be set in the config and they will be used as a fallback.

The default with parameters can be set for basket, wishlist, product, productCategory, category, search and variant.

let config = {
    withParams: {
        product: {
            attributes: {
                withKey: [
                    'color',
                    'brand',
                    'name',
                ],
            },
            advancedAttributes: {
                withKey: [
                    'productDescription',
                ],
            },
            variants: {
                attributes: {
                    withKey: ['price', 'size'],
                },
                lowestPriorPrice: true,
            },
            categories: 'all',
            priceRange: true,
            lowestPriorPrice: true,
        },
        search: {
            products: {
                attributes: {
                    withKey: ['color', 'brand', 'name'],
                },
                priceRange: true,
                categories: 'all',
            },
            categories: {
                parents: 'all',
                children: 10,
            },
        }
    }
}

Custom RPC Methods

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

let config = {
    rpcDir: './rpcMethods',
    rpcMethodNames: ['getContentFromCMS', 'callCustomMiddleware'],
}

Find out more about RPC Methods.

Runtime Configuration

How Storefront Core can be configured at runtime with environment variables.

Overview

Some parts of the Storefront Core configuration can and should be specified through runtime environment variables. This is for multiple reasons:

  1. Security.
    1. Confidential information such as API tokens should not be checked into source repositories or included in the compiled assets. Instead, those values should be saved in a secure location and loaded at runtime.
  2. Build once; deploy anywhere.
    1. It is DevOps' best practice to build your application once and promote the release through different environments. This workflow eliminates possible inconsistencies. Allowing configurations to be overridden at runtime enables this practice. For example, production and staging environments can be running the same build, but the production domain is set to myshop.example.com, while staging uses myshop.staging.example.com.
  3. Local development.
    1. Similar to the above, local development environments are often quite different from live environments. Live environments might be served behind nginx which provides HTTPS, while local dev servers configure HTTPS in the node. Live servers might use Redis as a cache, while local development has an in-memory or no cache. Controlling these overrides in a .env file that is not checked in.

NUXT_STOREFRONT_ environment variables

Storefront Core module settings can be overridden with environment variables that match a certain format. They should begin with NUXT_STOREFRONT and be followed by an upper-snake-case version of the property name.

Most of the storefront-nuxt configuration can be set at runtime and the module takes care of configuring runtimeConfig so storefront developers only need to provide the environment variables.

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

NUXT_STOREFRONT_REDIS_HOST=localhost
NUXT_STOREFRONT_REDIS_PORT=6379

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

NUXT_STOREFRONT_SHOPS_1001_DOMAIN=en.staging.demo.test
NUXT_STOREFRONT_SHOPS_1002_DOMAIN=de.staging.demo.test
NUXT_STOREFRONT_SHOPS_1003_DOMAIN=at.staging.demo.test

The number in the middle 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 here.

.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

How Storefront Core can be configured at compile-time with environment variables.

Overview

Last but not least, the Storefront Core can be configured by build-time environment variables. These are used to enable opting out of certain features and also exclude unnecessary code and dependencies.

To use these variables, make sure they are set when running nuxt build. The nuxt build command automatically loads the .env file if present, so that is one option.

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

Previous
Basic Setup
Next up
Authentication