docs
  1. Developer Guide
  2. Getting Started
  3. Set Up Your Storefront

Set up your Storefront

Overview

The SCAYLE Storefront Application is built on top of Nuxt, Vue, and Tailwind CSS frameworks, leveraging TypeScript for type safety. This guide will walk you through the essential steps to set up your local development environment and run the application in both preview and production-like modes.

Before You Start: Prerequisites

Before you begin the installation process, ensure you have the following necessary tools installed locally:

PackageVersion
git
nodeLTS (currently v22.14.0)
yarnv1
docker

Tool Installation Guide

Install Node.js

We recommend using nvm (Node Version Manager) to install and manage Node.js versions:

  1. Run nvm install lts/* to download and install the latest supported Node.js LTS version.
  2. Run nvm use lts/* to set this newly downloaded Node.js version as active for your terminal session.

Install yarn

Yarn is used for dependency management:

Install Storefront Application

The following steps outline the Storefront Application installation process:

  1. Get the Storefront Application source code from GitLab.
  2. Install dependencies.
  3. Configure application.
  4. Create HTTPS certificate.

1. Get the Storefront Application Source Code

The source code of available SCAYLE Storefront Application release versions is distributed via a GitLab repository.

Access the Repository: Contact your SCAYLE Account Manager to obtain your GitLab Access Token (OAUTH token).

This GitLab Access Token provides read-only access via the command line using git to clone the storefront-boilerplate-nuxt-public repository. It doesn't grant additional access rights or ability to access the repository via the GitLab UI.

Use the git clone command to checkout the latest source code using OAUTH via HTTPS:

2. Install Dependencies

Navigate into your Storefront Application directory:

Then, install all required dependencies:

Set Up Redis (with Docker)

Redis is used for caching and sessions. Ensure Docker is running on your machine.

  1. Open a terminal and navigate to your Storefront Application directory, where the docker-compose.yml file is located.
  2. Start the Redis service:\
  3. Verify Redis is running by checking the container status:\
  4. Check the official Redis documentation for additional details.

3. Configure Application

The SCAYLE Storefront command-line interface (CLI) tool accelerates feature adoption in SCAYLE Storefront tenant projects by simplifying the integration of new features and updates from the Storefront Application.

The setup command initializes a Storefront Application by fetching available shops from the SCAYLE Admin API using the provided tenant space.

Prerequisites

To run the setup, you need an Admin API token and the tenant space. Please follow the instructions in Create an Admin API Token to generate one.

Setup Command

To configure the Storefront Application using the CLI, run:

During this setup, you will be prompted to select a shop, after which the necessary configuration files .env, shops.ts, and locale translation files—will be automatically generated.

Additional Secrets

To run the Application, you still need to create and configure a few secrets:

SecretUsed forEnvironment Variable (.env)
Storefront API KeyRequired for authenticating requests to the Storefront API.NUXT_STOREFRONT_SAPI_TOKEN
Checkout Auth CredentialsUsed for OAuth authentication with SCAYLE Checkout, enabling custom login forms.

NUXT_STOREFRONT_OAUTH_CLIENT_ID

NUXT_STOREFRONT_OAUTH_CLIENT_SECRET

Checkout Token & SecretRequired for the Checkout Web Component (provided by your SCAYLE Account Manager).

NUXT_STOREFRONT_SHOPS_CHECKOUT_TOKEN

NUXT_STOREFRONT_SHOPS{SHOP_ID}_CHECKOUT_SECRET

4. Create a Local HTTPS Certificate

Features like Checkout require a working HTTPS connection. We recommend using the mkcert tool to generate a local certificate and key.

Create a local HTTPS certificate, as features like Checkout require a working HTTPS connection.

To generate a certificate and key, we recommend using the mkcert tool.

  1. Follow the mkcert installation instructions (Github).
  2. After installation, run:\
  3. Add both the generated local key and certificate file paths to your .env file:\

Your project will now be served on https://localhost:3000.

How To Turn Off Local HTTPS

As the local HTTPS encryption is directly coupled to the HTTPS_KEY and HTTPS_CERT, simply remove or comment out the entries in your .env-file, like this:

Run Your Application

Run a Development Preview

  1. Open a new terminal.
  2. Start a redis-server.
  3. Navigate to your Storefront Application.
  4. Run yarn dev:
    1. yarn dev → Starts the Nuxt development server with hot-reloading enabled.
    2. Uses the configuration from .env or nuxt.config.ts.
  5. Open your project at http(s)://localhost:3000/.

Run a Production-Like Preview

To start a production-like preview, run:

  1. Open a new terminal.
  2. Start a redis-server
  3. Navigate to your Storefront Application:
  4. Build the latest changes:
    1. yarn build → Compiles your Nuxt 3 app into static assets & server bundle inside the .output/ directory.
    2. This command optimizes and minifies the code for production.
  5. Then, run yarn preview:
    1. yarn preview → Runs the built Nuxt app from the .output/ directory.
    2. This simulates how the app will work in a real production server environment.
  6. Open your shop at http(s)://localhost:3000/ .

The local application will run over https if you set it up using the steps described in Create a Local HTTPS Certificate.

Manual Environment & Shop Setup (Advanced / Alternative)

If you prefer to set up your environment and shops manually instead of using the CLI tool:

  1. Create a local .env file: This file will hold all the application's relevant credentials, secrets, and override values. The Storefront Application contains a .env.example file you can copy and populate with your credentials. For an in-depth explanation of the required environment variables, see Configuration.\
    Important: Environment variables for shop-specific settings, defined in the .env.example file, must include a {UNIQUE_IDENTIFIER} for each shop. These variables need to be duplicated for every shop that will be run from the project. The {UNIQUE_IDENTIFIER} should match either the shop.shopId (recommended) or the shop.locale used in the shops.reduce function in config/storefront.ts:
  2. Update locales: The Storefront Application typically includes de-DE and en-US locales by default. To ensure your application starts properly, adjust the locales array in config/storefront.ts to match your existing shop configurations and replace the example shopIds with your actual shopIds from the SCAYLE Panel (Shops ➜ Dashboard).\
  3. Update shops: Adjust the shops array in nuxt.config.ts to reflect your existing shop configurations.\

{% hint style="success" %}

RECOMMENDED:
if [shop.shopId] is used -> Overrideable environment variable: NUXT_STOREFRONT_SHOPS_1001_CHECKOUT_USER
if [shop.locale] is used -> Overrideable environment variable: NUXT_STOREFRONT_SHOPS_EN_US_CHECKOUT_USER

{% endhint %}

Recommended: Use overrideable environment variables based on the shop identifier:

  • If shop.shopId is used → use
    NUXT_STOREFRONT_SHOPS_1001_CHECKOUT_USER
  • If shop.locale is used → use
    NUXT_STOREFRONT_SHOPS_EN_US_CHECKOUT_USER

Further Education – SCAYLE Academy

Storefront

Storefront Crash Course

  • Intermediate
  • 5 lessons
  • 1h 55m
Play tutorial
Previous
What is Storefront?
Next up
Basic Theming