Build configuration

A site's build configuration is four things: what installs dependencies, what builds, where the output lands, and which runtime the build runs on. Set them once and every deployment uses them.

The four settings

Two more sit alongside them and change what the build means:

For a static single-page app, also set a fallback file (usually index.html) so client-side routes resolve instead of 404ing. Cockpit labels this field Fallback file (SPA).

The same screen also carries the Server specification and the Timeout (seconds) — see Compute specifications — plus Enabled and Logging toggles. Saving them is a separate action (Save settings) from saving the Git deploy triggers (Save triggers).

They belong to the site

Build settings are properties of the site, not files in your repository. That has two consequences worth internalising:

• They apply to the next deployment. Changing the build command does not change the running build. Create a new deployment for it to take effect — see Deployments.
• You set them in one of three equivalent places. Cockpit under Experience Studio → Sites, the CLI, or the API.

revenexx sites update \
    --site-id <SITE_ID> \
    --framework nuxt \
    --adapter ssr \
    --install-command 'npm install' \
    --build-command 'npm run build' \
    --output-directory './.output'

The same flags work on revenexx sites create, plus --build-runtime, --specification, --fallback-file and --timeout.

A theme declares its own defaults in the manifest, which is why a scaffolded theme deploys correctly with no configuration:

{
  "site": {
    "framework": "nuxt",
    "adapter": "ssr",
    "installCommand": "npm install",
    "buildCommand": "npm run build",
    "outputDirectory": ".output"
  }
}

Per-deployment overrides

The site's settings are the defaults; a single deployment can be created with different ones. That's what revenexx deploy exposes:

revenexx deploy site . \
    --framework nuxt \
    --adapter ssr \
    --install-command 'npm ci' \
    --build-command 'npm run build:staging' \
    --output-directory './.output'

Use it for a one-off — reproducing a CI build locally, testing a different build command before committing to it. Don't use it as your normal path: an override that only exists in someone's shell history is a build nobody else can reproduce. Put the real values on the site.

Defaults per framework and adapter

These are what the platform applies when you don't override them. Override any of them in the site's build settings when your project differs.

Note the two that catch people out: Nuxt's static build uses npm run generate, not npm run build; and Next.js changes its output directory entirely between adapters.

Project dependencies

Dependencies install during the build, using the site's install command. Two rules:

• Commit your dependency manifest and lockfile. The build installs from the public registry, so every dependency must resolve there.
• Do not commit node_modules. Packages built for your local OS may not work in the build environment, and you'll be debugging a machine mismatch instead of your code.

The build runs a plain install — not a workspace install — so a theme that depends on an unpublished workspace package will build locally and fail on the platform.

Request timeout

Each request to a server-rendered storefront has a time limit, set per site, up to a maximum of 30 seconds. Set it with --timeout on revenexx sites create or update.

If you're hitting it, the fix is almost never a longer timeout — it's moving the slow call off the render path. Render the page shell server-side and fetch the slow, buyer-specific parts (price, stock) after paint. See Catalog, cart and checkout.

Debugging

• Build succeeds locally, fails on the platform. The build runs a plain install against the public registry. Every dependency must resolve from npm, and your lockfile should be committed.
• A configuration change had no effect. Build settings apply to the next deployment. Create one.
• The build succeeds but the site serves nothing. The output directory is wrong, or the build wrote somewhere else. Check it against the table above for your framework and adapter.
• The build ran out of memory. Raise the server specification, or give Node more heap in the build command — see Compute specifications.
• Declaring ssr failed the build. That's intentional: if the build produced only static files, the platform fails the build rather than serving something that won't run.

Related

• Compute specifications — the build and runtime sizes
• Environment variables — what the build and runtime receive
• Frameworks — the fifteen supported frameworks and adapter detection
• Rendering — the per-framework configuration for SSR and static
• Deployments — statuses and build logs