Setup your Storefront

Overview

Storefront Boilerplate is built on top of Nuxt, Vue and Tailwind CSS frameworks and uses TypeScript.
The Frameworks section provides a comprehensive list of links to documentation of all relevant technologies.

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 to have installed:

• git - source code version control
• nvm - Node Version Manager
• node - v20.7.0 or newer
• yarn - v1
• redis

Install Node.js

To install the supported Node.js version, we recommend to use of 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 Redis

Installing redis locally version of redis / redis-server is sufficient.

Check Redis documentation for details.

Install yarn

bash

Copy

npm install --global yarn

Install Storefront Boilerplate

To install Storefront Boilerplate, follow these steps:

1. Get credentials:
   1. GitLab Access Token (OAUTH token).
   2. Get API keys.
2. Get the Storefront Boilerplate source code from GitLab.
3. Install dependencies.
4. Create local .env file
5. Update locales.
6. Create HTTPS certificate.

Get credentials

Get GitLab Access Token

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

Get API keys

You can get your API keys in the SCAYLE Panel:

1. Go to Settings > General > API Keys.

Get the Storefront Boilerplate source code

The source code of available SCAYLE Storefront Boilerplate release versions is distributed via the GitLab repository (storefront-boilerplate-nuxt-public).

The Storefront Boilerplate GitLab repository requires a GitLab Access Token.

Access the storefront-boilerplate-nuxt-public repository

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

git

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, run:

Copy

yarn install

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 Boilerplate contains a .env.example file you can copy and populate with your credentials.

Values to add or replace

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.

Update locales

Storefront Boilerplate 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 shops = [
  {
    locale: 'de-DE',
    path: 'de',
    shopId: 1001,
    currency: 'EUR',
    isDefault: true,
  },
  {
    locale: 'en-US',
    path: 'en',
    shopId: 1028,
    currency: 'USD',
  },
]

1. In the nuxt.config.ts:
   • Adjust the default locales to your existing locales

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',
  },
]

Create local HTTPS certificate

Create a local HTTPS certificate, as features like Checkout will 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.pem
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. Start a local redis-server instance.
2. Run yarn dev to start the local dev server of Storefront Boilerplate / Nuxt 3.
3. Use http://localhost:3000/ to open the project.

Run a production-like preview

To start a production-like preview, run:

1. Start a local redis-server instance
2. To build latest changes: yarn build
3. Then: yarn preview
4. Use http://localhost:3000/ to open the shop.

This will run the generated Nuxt application from the .output/ directory, similar to how the application will be deployed on a production server. The only difference is that all relevant NUXT_ runtimeConfig override values are sourced from the local .env file.

Frameworks

As the Storefront Boilerplate uses frameworks like Nuxt and Vue as its foundation, most configuration and usage examples from its respective documentation can and should be used as additional references.

Documentation of used technologies:

Nuxt

• Nuxt - Get Started
• Nuxt - Guide
• Nuxt - API
• Nuxt - Examples
• Nuxt - Community

Vue

• Vue - Getting Started
• Vue - Tutorials
• Vue - Examples
• Vue - Quick Start
• Vue -Glossary
• NVue - API

VueUse (Utilities for Vue)

• VueUse - Getting started
• VueUse - Best Practice
• VueUse - Configuration
• VueUse - Components
• VueUse - All (Utility) FUnctions
• VueUse - AddOns

Vuelidate (Input validation for Vue)

• Vuelidate - Getting started
• Vuelidate - Guide
• Vuelidate - Advanced Usage
• Vuelidate - Examples
• Vuelidate - Built-in Validators
• Vuelidate - Custom Validators

Tailwind CSS

• Tailwind - Get started
• Tailwind - Core Concepts / Utility-First Fundamentals
• Tailwind - Configuration
• Tailwind - Resources

Vite (build tool)

• Vite - Getting started
• Vite - Configuration
• Vite - PLugins

Vitest (Unit testing)

• Vitest - Getting started
• Vitest - API
• Vitest - Configuration
• Vitest - Advanced
• Vitest - Nuxt module

Playwright (End-to-End testing)

• Playwright - Getting started
• Playwright - End-to-End Testing
• Playwright - Component Testing

Further education - SCAYLE Academy

Storefront

Storefront Crash Course

• Intermediate
• 5 lessons
• 1h 55m

Play tutorial