Setup your Storefront

Overview

The SCAYLE Storefront application is built on top of Nuxt, Vue and Tailwind CSS frameworks and uses TypeScript.

This guide will show you how to set up your local environment and test in preview and production-like modes.

Before You Start

Make sure you have the following necessary tooling installed locally:

Install Node.js

To install the supported Node.js version, we recommend using the nvm (Node Version Manager).

1. Run nvm install lts/* to download and install the latest supported Node.js version.
2. Run nvm use lts/* to use the freshly downloaded node version.

Install yarn

bash

Copy

npm install --global yarn

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. Configuration Setup
4. Create HTTPS certificate.

Get the Storefront Application Source Code

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

Contact your SCAYLE Customer Success Manager to get your GitLab Access Token (OAUTH token).

Access the storefront-boilerplate-nuxt-public Repository

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

sh

Copy

git clone https://oauth2:{INSERT_GITLAB_ACCESS_TOKEN_HERE}@gitlab.com/aboutyou/scayle/core-engine/storefront-unit/storefront-core/storefront-boilerplate-nuxt-public.git

Install Dependencies

To install all required dependencies, navigate to your Storefront application directory:

bash

Copy

cd storefront-boilerplate-nuxt-public

and run:

bash

Copy

yarn install

Setup Redis

1. Install Docker (if not already installed).
2. Open a terminal and navigate to the directory containing the docker-compose.yml file in your Storefront application
3. Start redis:

bash

Copy

docker compose up -d redis

4. Verify Redis is running by connecting to the container:

bash

Copy

docker compose ps

5. Check the official Redis documentation for additional details.

Configuration Setup

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:

bash

Copy

npx @scayle/storefront-cli setup --admin-api-token=<YOUR_TOKEN> --tenant-space=<TENANT_SPACE>

During 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 be able to run the application, you still need to create and configure a few secrets:

Create a Local HTTPS Certificate

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.
Follow the mkcert installation instructions (Github) and afterward run:

sh

Copy

mkcert --key-file localhost.pem --cert-file localhost.crt localhost

After generating the local key and certificate file, add both to your .env-file as follows

yaml

Copy

HTTPS_KEY=localhost.pm
HTTPS_CERT=localhost.crt

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:

ini

Copy

# HTTPS_KEY=localhost.key
# HTTPS_CERT=localhost.crt
SOME_OTHER_ACTIVE_KEY=someValue

Run Your Application

Run a preview of your application

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. Use http(s)://localhost:3000/ to open the project.

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
   1. bash

      Copy

      cd /path/to/storefront-application
      

4. To build the latest changes: yarn build
   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: 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. Use http(s)://localhost:3000/ to open the shop.

Further Education - SCAYLE Academy

Storefront

Storefront Crash Course

• Intermediate
• 5 lessons
• 1h 55m

Play tutorial

Setup Environment And Shops Manually

Create a local .env file

For an in-depth explanation of the required environment variables, see Configuration.

To start up the shop application locally, create a local-only .env file.
This .env file will hold all the application's relevant credentials, secrets, and override values.

Storefront application contains a .env.example file you can copy and populate with your credentials.

Environment variables defined in the .env.example file must have a {UNIQUE_IDENTIFIER} on a per shop base. They need to be duplicated for every shop that will be run from the project.

It is important to replace the placeholder of {UNIQUE_IDENTIFIER} to be equal to the key (shop.shopId or shop.locale) set of the shops.reduce function in config/storefront.ts.

{% hint style="info" %}

We strongly recommend using the shopId as {UNIQUE_IDENTIFIER}!

{% endhint %}

Update Locales

Storefront application contains these locales by default:

• de-DE (Germany)
• en-US

For your application to start properly, you need to match the configuration files and your shopIDs.

Find ShopID in the SCAYLE Panel: Shops > Dashboard.

1. In the config/storefront.ts:
   • Adjust the defaults to your existing locales
   • Replace the ShopId

typescript

Copy

const locales = [
  {
    code: 'de',
    iso: 'de-DE',
    domain: DOMAIN_PER_LOCALE ? domains.de : domains.default,
    file: 'de-DE.json',
  },
  {
    code: 'en',
    iso: 'en-GB',
    domain: DOMAIN_PER_LOCALE ? domains.en : domains.default,
    file: 'en-GB.json',
  },
]

2. In the nuxt.config.ts:

• Adjust the default locales to your existing locales

typescript

Copy

const shops = [
  {
    locale: 'de-DE',
    path: 'de',
    shopId: 1001,
    currency: 'EUR',
    isDefault: true,
  },
  {
    locale: 'en-US',
    path: 'en',
    shopId: 1028,
    currency: 'USD',
  },
]

{% 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 %}