Site manifest

The site manifest is the document Showly uses to know how to build, deploy, and serve your site. It lives at the root of your imported workspace as showly.json. It's the source of truth for every build — auto-detection produces an initial version on import; you can hand-edit it any time.

Every field is optional except rootDirectory, which defaults to .. Showly fills in sensible defaults from auto-detection, so a minimal valid manifest can be an empty object.

Shape

{
  "rootDirectory": ".",
  "runtime": "node",
  "runtimeVersion": "22",
  "packageManager": "pnpm",
  "installCommand": "pnpm install",
  "buildCommand": "pnpm build",
  "output": {
    "type": "static",
    "directory": "dist"
  },
  "startCommand": "node server.js"
}

Field reference

rootDirectory — The directory within the repository that contains the site. Defaults to .. Set this when a single repo holds a site in a subdirectory.

runtime — The execution runtime for the deployed site. One of static, node, rust, go, or docker. If omitted, Showly infers it from the detected framework.

runtimeVersion — The runtime version (for example, the Node major version). Showly supports the current Active LTS lines; the live set is at GET /admin/platform/runtime-catalog.

packageManager — The package manager to use (for example, pnpm, npm, or yarn). Defaults to the one detected from the lockfile.

installCommand — The shell command that installs dependencies. Defaults to the package manager's standard install command.

buildCommand — The shell command that produces a deployable artifact. Defaults to the framework's standard build command but you can supply your own.

output — Where and how the build emits its artifact. A nested object with two optional keys: type (the artifact kind) and directory (the path the build writes to, relative to rootDirectory).

startCommand — The command that starts the server for runtimes that run a long-lived process (for example, node). Static sites don't need one.

Framework detection

framework is not a manifest input — Showly auto-detects it from package.json, the lockfile, and other repository conventions. The detected value is one of astro, vite, next-export, static-html, custom, or unknown. If the framework resolves to unknown, the build fails with an UnsupportedFrameworkError; set runtime and the relevant commands explicitly to deploy a project Showly can't classify.

When to hand-edit

• You changed your build command and want Showly to follow.
• Your repo has the site in a subdirectory — set rootDirectory.
• Auto-detection guessed the runtime wrong — set runtime explicitly.
• Your install or start command differs from the package manager default.

Validation and failure modes

• If showly.json is not valid JSON, or parses to something other than an object, the build fails with an InvalidManifestError.
• If the framework can't be classified (resolves to unknown), the build fails with an UnsupportedFrameworkError.

What the manifest does not control

• Environment variable values — those are set per-environment in the Showly UI and live in the secrets store.
• Approval rules — those are workspace policy.
• Deploy target (Cloud Run vs static CDN) — that's a deployment-target setting.

The manifest is _what the build looks like_. Workspace settings are _who can do what to the result_.