Configuration

Configuration

SPACK user-facing configuration is documented in the GitHub Wiki. Runtime defaults, CLI flags, environment variables, and config files should stay compatible with the documented contract for a release line.

API version

SPACK runtime configuration uses an explicit API version:

apiVersion: spack.io/v1alpha1
kind: RuntimeConfig

The version gives SPACK a migration path for future field renames, default changes, and deprecations.

Minimal runtime config

Serve a frontend dist/ directory directly:

apiVersion: spack.io/v1alpha1
kind: RuntimeConfig

assets:
  root: /app
  path: /
  entry: index.html
  fallback:
    on: not_found
    target: index.html

Serve a compiler-produced .spack bundle:

apiVersion: spack.io/v1alpha1
kind: RuntimeConfig

assets:
  root: /app/app.spack
  path: /
  entry: index.html
  fallback:
    on: not_found
    target: index.html

Configuration precedence

Configuration sources are merged in this order. Later sources override earlier ones:

1. built-in defaults
2. .env and .env.local
3. files passed by --config
4. environment variables
5. CLI flags

CLI flags use config-path names, for example --compression.mode=warmup.

Compiler optimization settings

Compression and image optimization are compiler-side responsibilities. The runtime can still serve a plain source directory directly, but AOT bundles can include precomputed compressed variants, image variants, resource hints, and index metadata.

The image compiler path uses libvips. Building image variants requires CGO, libvips runtime libraries, and libvips development metadata available through pkg-config.

image:
  enable: true
  widths: "640,1280,1920"
  formats: ""
  jpeg_quality: 78
  max_source_bytes: 10485760
  max_source_pixels: 25000000
  max_width: 10000
  max_height: 10000
  max_output_variants: 12
  max_concurrent_sources: 2
  max_memory_bytes: 134217728
  min_saving_ratio: 0.05
  min_saving_bytes: 1024

Image generation is batched per source asset: SPACK decodes a source image once, builds a width pyramid, and encodes requested width/format variants from that batch. Variants that do not meet saving thresholds are not written to the bundle or artifact output.

max_memory_bytes is a global estimated decoded image memory budget shared by image generation work in the engine instance. A batch estimates source and pyramid memory before full decode and waits for budget capacity; if one batch exceeds the budget it is skipped.

Stale asset recovery

frontend.stale_asset_recovery.enable is true by default. Disable it when a missing asset should remain a 404:

frontend:
  stale_asset_recovery:
    enable: false

After a deployment, an old HTML page may request a fingerprinted JavaScript chunk that no longer exists, such as assets/chunk.abc123def456.js. If the runtime cannot resolve that request, stale asset recovery returns a small JavaScript response with HTTP 200, Content-Type: application/javascript, and Cache-Control: no-store. The script calls location.reload() to request the current page again. The same setting applies to direct-directory and AOT bundle delivery.

This is a fallback for missing fingerprinted .js requests, not a browser-cache version check. It does not apply to CSS, images, or non-fingerprinted JavaScript. A request served entirely from a browser cache, service worker, or CDN never reaches this fallback. A reload can still receive stale HTML if an upstream cache does not revalidate it. Keeping old chunks available during a deployment is more reliable when uninterrupted sessions are required.

Deployment checks

Validate a file without starting the server:

spack config validate --file spack.yaml

Print the effective configuration after merging defaults, config files, environment variables, and CLI flags:

spack config print-effective --file spack.yaml --redact

--redact hides local filesystem paths such as assets.root, compression.cache_dir, and logger.file.path.