Set up your Storefront

Overview

This guide walks you through setting up your local development environment, configuring the application, and running it in both development and production-like modes.

For information about what the Storefront Application is and its architecture, see What is Storefront?.

Prerequisites

Before you begin, ensure you have the following tools installed:

Install Node.js with NVM

The Storefront Application requires Node.js v22.19.0 or higher. nvm (Node Version Manager) simplifies installing and managing multiple Node.js versions.

bash

Copy

Installing PNPM with Corepack

The Storefront Application uses PNPM as its package manager. Enable Corepack (included with Node.js) to manage package manager versions:

bash

Copy

Set up Storefront Application

Step 1: Get the Source Code

The Storefront Application source code is distributed via a GitLab repository. Contact your SCAYLE Account Manager to obtain your GitLab Access Token (OAUTH token).

Clone the repository using the OAUTH token:

sh

Copy

Step 2: Install Dependencies

Navigate to the project directory and install all required dependencies:

bash

Copy

Step 3: Set Up Redis

Redis is required for caching and session management. The application includes a Docker Compose configuration for easy Redis setup.

Start the Redis service:

bash

Copy

The Redis service runs on port 6379 and is accessible at localhost:6379.

Step 4: Configure Application

The SCAYLE Storefront CLI setup command simplifies the initial configuration by automatically generating configuration files based on your SCAYLE tenant space.

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

Prerequisites for CLI setup

• Admin API token from the SCAYLE Panel
• Tenant space identifier

Run the setup command

bash

Copy

The CLI tool performs the following actions:

• Fetches available shops from the SCAYLE Admin API
• Prompts you to select a shop
• Generates the .env configuration file
• Creates config/shops.ts with shop configurations
• Generates locale translation files in i18n/locales/

Configure CMS (Optional)

To set up a CMS provider (Storyblok or Contentful), run the CMS setup command:

bash

Copy

This command guides you through selecting a CMS provider and configuring the necessary options. For detailed CMS integration instructions, see the CMS Integrations documentation.

Step 5: Configure Additional Secrets

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

Step 6: Create Local HTTPS Certificate

Features like Checkout require a working HTTPS connection. Generate a local HTTPS certificate using the mkcert tool.

Install mkcert

Follow the mkcert installation instructions for your operating system.

Generate certificate

bash

Copy

Add to local .env file

ini

Copy

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

To disable HTTPS

Remove or comment out the HTTPS_KEY and HTTPS_CERT entries in your .env file:

ini

Copy

The application will then run on http://localhost:3000.

Run Your Application

Step 7: Development Mode

Start the development server with hot-reloading:

bash

Copy

The development server starts on http://localhost:3000 (or https://localhost:3000 if HTTPS is configured). Open your browser and navigate to the URL.

Step 8: Production-Like Preview

Build and preview the application in a production-like environment:

bash

Copy

The preview server runs the built application from the .output/ directory, simulating how the application works in a production environment. Ensure Redis is running before starting the preview server.

Configuration

For detailed configuration options, see the Configuration Guide.

Shop Configuration

Shop configurations are defined in config/shops.ts. The Storefront CLI setup tool automatically generates this file. For manual configuration, see the Configuration Guide.

Environment Variables

The Storefront Application uses environment variables for runtime configuration. All Storefront-related variables that are not build-relevant use the NUXT_ prefix. Shop-specific variables use the pattern NUXT_STOREFRONT_SHOPS_{UNIQUE_IDENTIFIER}_{SETTING}, where {UNIQUE_IDENTIFIER} should match either shop.shopId (recommended) or shop.locale used in your shop configuration.

Best Practices

Shop Identifier Usage

Use shop.shopId as the unique identifier in shop configurations rather than shop.locale. This approach avoids conflicts when multiple shops share the same locale and provides clearer environment variable naming.

Environment Variable Management

• Keep sensitive values in .env files and never commit them to version control.
• Use .env.example as a template for required variables.
• Document any custom environment variables in your project documentation.
• Use descriptive variable names that clearly indicate their purpose.

Development Workflow

• Always ensure Redis is running before starting the development server.
• Use HTTPS in development when testing Checkout or other features that require secure connections.
• Test both development and production-like preview modes before deploying.
• Verify shop configurations match your SCAYLE Panel settings.

Configuration Validation

• Verify that shop IDs in config/shops.ts match your SCAYLE Panel shop IDs.
• Ensure translation files exist for all configured locales.
• Check that environment variables use the correct shop identifier format.
• Validate Redis connectivity before running the application.

Troubleshooting

Further Education – SCAYLE Academy

Storefront

Storefront Crash Course

• Intermediate
• 5 lessons
• 1h 55m

Play tutorial