Builds

Builds turn source into a running StackMachine app version. Send files or a ZIP archive, define install/build/start commands, stream logs while the build runs, and receive the live app URL when the version is ready.

Features

Files and ZIP uploads

For small deploys, pass a files map directly to client.deployments.create. For larger bundles, upload a ZIP with client.files.upload and deploy from the returned uploadUrl.

Build commands

Set installCmd, buildCmd, and startCmd so StackMachine can install dependencies, compile assets, and boot the runtime process.

Streaming progress

The returned deployment is created immediately with a build ID. Call deployment.wait and attach onProgress to watch stdout, stderr, runtime messages, and build lifecycle events.

Repeatable releases

Use allowExistingApp when pushing a new version of an existing app. StackMachine creates a fresh app version while preserving the app identity and domains.

Common workflow

Prepare source files and optional environment variables.
Create a deployment with inline files or an uploaded ZIP URL.
Wait for the build to finish and inspect progress logs.
Use the returned app version to open the live URL or fetch runtime logs later.

SDK examples

Create and wait for a build

This example builds a JavaScript app from inline files, custom commands, and environment variables.

builds.js

const deployment = await client.deployments.create(
  {
    appName: "edge-storefront",
    owner: "stackmachine",
    files: {
      "package.json": JSON.stringify({
        type: "module",
        scripts: {
          build: "node build.js",
          start: "node server.js",
        },
        dependencies: {},
        devDependencies: {},
      }),
      "build.js": [
        'import { mkdirSync, writeFileSync } from "node:fs";',
        'mkdirSync("dist", { recursive: true });',
        'writeFileSync("dist/index.html", "<h1>Hello from StackMachine</h1>");',
      ].join("\n"),
      "server.js": [
        'import { createServer } from "node:http";',
        'import { readFileSync } from "node:fs";',
        "",
        "createServer((req, res) => {",
        '  res.setHeader("content-type", "text/html");',
        '  res.end(readFileSync("dist/index.html"));',
        "}).listen(Number(process.env.PORT || 3000));",
      ].join("\n"),
    },
    installCmd: "npm install",
    buildCmd: "npm run build",
    startCmd: "npm start",
    envVars: [{ name: "NODE_ENV", value: "production", sensitive: false }],
  },
  {
    onUploadProgress: ({ percent }) => console.log("upload", percent),
  },
);
 
const appVersion = await deployment.wait({
  onProgress: ({ datetime, stream, message }) => {
    console.log(datetime, stream, message);
  },
});
 
console.log(appVersion.app.url);

Source: stackmachine/sdks JavaScript examples.