Build Configuration

The Build stage transforms your Storefront Application code into a deployable artifact. To simplify the process and remove the need to manage complex build configurations, SCAYLE uses a standardized container image in the background so you don't need to provide a Dockerfile in your repository.

The only required configuration for the build process is specifying a Node.js version constraint in the engines.node field of your package.json. This tells the platform which Node.js version to use for the build.

Node.js Version Selection

Storefront Hosting supports every Node.js major version that is in Active LTS or Maintenance LTS on the official Node.js release schedule. When a version reaches end of life, it is removed from the supported list right after. The source of truth for LTS status and end-of-life dates is the Node.js previous releases page.

Supported versions

Configuring the version

Set the engines.node field in your package.json. When a build is triggered, the platform resolves the constraint using standard semver rules and selects a supported Node.js image accordingly.

json

Copy

The caret (^) in ^24.0.0 locks the build to the Node.js 24 major version. The platform selects the newest 24.x.x image available at build time, so your build runs on the latest security patches and performance improvements within Node.js 24.

When the constraint matches no supported version

The platform resolves engines.node using standard semver rules at the start of each build. If no supported major version satisfies the constraint, image selection fails during the build step and an error message appears in the build logs. There is no preflight check in the SCAYLE Panel - validation only happens at build time.

Where the active version is shown

The Node.js version used by the current deployment is shown as a Panel field under:

Shops ➜ [Shop] ➜ Hosting ➜ Overview

Shops ➜ [Shop] ➜ Hosting ➜ Deployments ➜ [Deployment]

So you can see at a glance which Node.js major version each environment is running.

URL Base Path

By default, your Storefront Application is served from the domain root (e.g., example.com/). If your storefront needs to be served from a URL sub-path (e.g., example.com/store/), configure the basePath inside a scayle object in package.json:

json

Copy

Fields:

• framework - the Storefront framework your application uses. Required when basePath is set.
• basePath - the URL sub-path where your storefront is served. Optional. When set: must be non-empty, must start with /, cannot be just /. A trailing slash is accepted.

When basePath is set, the platform serves all storefront routes - pages, API endpoints, health checks, and build assets - under the prefix. Requests to the exact root / redirect to the base path.

Application-side configuration

Setting basePath in package.json is only one side of the setup. You also need to configure your Storefront Application to run under the same base path.

The basePath and your application's configuration must match - mismatches cause deployment failures.

Build Environment Variables

Storefront Hosting sets several environment variables automatically when it builds your Storefront Application. You can read these in your build scripts, nuxt.config, or anywhere in the build process.

The following variables are set on every build:

Example

Read a platform variable in your build script:

javascript

Copy

Availability

These variables are set during the build only - while dependencies are installed and the build script runs. They are not set in the running Storefront Application container, so runtime code must not read them.

For values you need at runtime, use Environment Variables instead.

Interaction with custom build arguments

Platform-provided variables sit next to any custom build arguments you configure per environment. A custom build argument with the same name overrides the platform value, so avoid defining custom arguments with names that clash with the variables listed above.