docs

Set Up Your Storefront

This guide takes you from a clone of the Storefront Application V3 to a storefront that runs on your machine and reads your SCAYLE shop. The Storefront CLI does most of the work. It reads your shop from the Admin API and writes your configuration, so you only supply the credentials it cannot fetch.

Prerequisites

  • Node.js v26. The .nvmrc file in the project root names it.
  • pnpm at the version in the packageManager field of package.json, or higher.
  • Docker, to run Redis locally.
  • mkcert, to create the certificate for local HTTPS.
  • A SCAYLE shop, and access to the SCAYLE Panel.
  • Your tenant space, which is the part before .panel.scayle.cloud in your SCAYLE Panel URL.
  • An Admin API token with read permission on the Shops resource. The CLI uses it to read your shop. Set up your shop explains how to create one.
  • The checkout credentials of each country, which your SCAYLE Account Manager provides. You can start without them, see Run the Storefront CLI.

Clone the repository

The source code of the Storefront Application V3 is available at github.com/scayle/storefront-application. Clone it and open the project's root directory:

Install dependencies

From your project's root directory:

Start Redis

The Storefront Application needs a Redis-compatible store for sessions and for caching Storefront API and CMS responses. A docker-compose.yml in the project root starts one for local development:

Confirm it's running:

This should print PONG.

The application connects to the store in cluster mode, the way SCAYLE KV runs. A plain local Redis is a single instance, so STOREFRONT_KV_DISABLE_CLUSTER_MODE has to be true. .env.example already sets it, so a .env made from that file has it. See Cache and SCAYLE KV.

Run the Storefront CLI

The setup command configures the project for your shop. Run it from your project root:

If you don't have the tenant space or the Admin API token at hand, run the command anyway. It prompts for both and prints the link to the Panel page where you create the token.

  1. Enter the tenant space and the Admin API token when the CLI prompts for them, then pick your shop from the list.
  2. The CLI asks whether the existing storefront.config.ts should be overridden, because the file is always there. Answer yes. With the default no, the CLI edits a copy named storefront.config.new.ts and your storefront.config.ts keeps its example countries.
  3. The CLI creates .env from .env.example and replaces the countries in storefront.config.ts with the countries of your shop. It also creates one translation file per country language. What setup writes lists each file. For each country, it writes placeholder text for the checkout credentials, so the application can start. Replace the placeholders with the values from your SCAYLE Account Manager before you use checkout.
  4. The CLI offers to generate a session secret. Press Enter to accept. It then asks for the values it cannot fetch from the Admin API: the Storefront API key, the OAuth client ID, and the OAuth client secret. Each of these prompts prints the Panel page where the value lives. Press Enter to skip one and fill in the value later.

The CLI prints Setup completed successfully! when it finishes. Set up your shop describes every prompt and flag, including a run without prompts for a script. Connect a CMS provider is the next command to run once you choose a CMS.

Setting up manually

If you don't have an Admin API token yet and prefer not to use the CLI, copy the example file and fill in the values by hand:

Then add your countries to storefront.config.ts. A working local setup needs every variable in Required, which explains what each one sets. Where the values come from:

  • STOREFRONT_TENANT_SPACE and STOREFRONT_SHOP_KEY: your tenant space and the key of your shop in the SCAYLE Panel.
  • STOREFRONT_COUNTRIES_<CODE>_SHOP_COUNTRY_ID: the shop country ID of each country you've configured in storefront.config.ts, for example STOREFRONT_COUNTRIES_DE_SHOP_COUNTRY_ID.
  • STOREFRONT_API_KEY: SCAYLE Panel ➜ Settings ➜ General ➜ API Keys.
  • STOREFRONT_OAUTH_CLIENT_ID and STOREFRONT_OAUTH_CLIENT_SECRET: SCAYLE Panel ➜ Shops ➜ your shop ➜ Storefront ➜ API Keys ➜ Customer Authentication API Keys.
  • STOREFRONT_SESSION_SECRET: a random string of at least 32 characters. It doesn't need to come from SCAYLE.
  • STOREFRONT_COUNTRIES_<CODE>_CHECKOUT_USER, _TOKEN, and _SECRET: the checkout credentials of each country you've configured in storefront.config.ts. Ask your SCAYLE Account Manager for them.

The .env.example file documents every other variable the application reads, including CMS provider tokens and OpenTelemetry export settings. These are all optional for a first run, and so are STOREFRONT_GTM_ID and STOREFRONT_USER_CENTRICS_APP_ID. See Integrations for where each one is documented.

Set up HTTPS

The development server runs over HTTPS only. The Storefront Application V3 relies on browser features that need a secure context, and the scheme of the dev server carries into every absolute URL the application generates, such as canonical and hreflang URLs. See Public origin.

mkcert creates a certificate that your browser already trusts. The commands below are for macOS. The mkcert repository lists the installation steps for other systems.

The dev server reads certs/localhost.crt and certs/localhost.key from the project root. To use certificates from a different location, set HTTPS_CERT and HTTPS_KEY in .env. Both file types are in .gitignore, so every clone of the project needs its own pair.

The dev server uses one certificate pair for every host. When countrySelector is 'domain', add every country domain you serve locally to the mkcert command, for example de.localhost. Routing and Countries explains the country selector.

Node.js ignores the system certificate store by default, so a request that the dev server sends to its own HTTPS address, such as the Open Graph viewer in the DevTools, fails with unable to verify the first certificate. The DevTools troubleshooting entry has the fix.

Run the development server

Open https://localhost:3000. You should see the storefront of your shop. Products and categories appear when your shop has them. The homepage shows a static welcome page until you connect a CMS provider. A launcher at the bottom of the page opens Storefront DevTools, which show the Inertia.js visits, page props, and oRPC calls of each page. The first time a browser connects, the dock asks for a one-time code that the pnpm run dev terminal prints.

Build and run a production build

To see how the application behaves once built, instead of through Vite's dev server:

pnpm run preview starts the built server with your .env file. The built server listens over plain HTTP, so open http://localhost:3000, not the HTTPS address of the dev server.

Troubleshooting

The dev server stops because the certificate files are missing

Issue: pnpm run dev stops at startup with Local TLS certificates are required for the dev server (HTTPS only). The message names the paths it expected.

Possible causes:

  • You haven't created the certificate files in this clone, or you created them in another directory.
  • HTTPS_CERT or HTTPS_KEY in .env points to a file that doesn't exist.

Solution:

  1. Run the mkcert commands from Set up HTTPS in the project root.
  2. Run pnpm run dev again.

Prevention: Create the pair once per clone. Both files are in .gitignore.

The storefront fails with a configuration error

Issue: Requests fail with an error that names a field of storefront.config.ts. A production server stops at startup instead, before it serves a request.

Possible causes:

  • A required variable is unset in .env, for example STOREFRONT_SESSION_SECRET, or it is shorter than 32 characters.
  • A country in storefront.config.ts has no matching STOREFRONT_COUNTRIES_<CODE>_* variables.

Solution: Compare .env with Required and set the variable the error names. Restart the dev server.

Prevention: Run the Storefront CLI instead of editing .env by hand. The startup check does not catch an empty STOREFRONT_API_KEY, so a wrong key shows up later as a failed Storefront API request. Validation at startup lists what the check misses.

The CLI does not recognize the project

Issue: setup prints does not contain a supported Storefront Application.

Possible causes:

  • You run the command outside the project.
  • The package.json of your project has no "scayle": { "framework": "storefront-v3" } entry, or the project has no storefront.config.ts.

Solution: Run the command from the project root. The CLI troubleshooting entry lists the other fixes.

Prevention: Keep scayle.framework in package.json when you edit it.