---
title: "Builds"
description: "Build source code into StackMachine Edge app versions."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.stackmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Builds

Deploy your app from source and let StackMachine build it for you. StackMachine automatically detects the language and framework, installs dependencies, and builds the app. Send source files or a ZIP archive, watch build progress, 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`.

### Automatic detection

Include your source, dependency manifests, and lockfiles. StackMachine detects how to install, build, and run the project, so you can omit install/build/start commands. Use `installCmd` / `install_cmd`, `buildCmd` / `build_cmd`, or `startCmd` / `start_cmd` when you need to override the detected commands.

### 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

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

## SDK examples

### Deploy source and watch the build

Both SDKs deploy this Node.js app from source. StackMachine detects its `package.json` and scripts; no command overrides or local build are needed.

```javascript
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"),
    },
    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);
```

```python
import json

deployment = client.deployments.create(
    app_name="edge-storefront",
    owner="stackmachine",
    files={
        "package.json": json.dumps({
            "type": "module",
            "scripts": {"build": "node build.js", "start": "node server.js"},
        }),
        "build.js": '\n'.join([
            'import { mkdirSync, writeFileSync } from "node:fs";',
            'mkdirSync("dist", { recursive: true });',
            'writeFileSync("dist/index.html", "<h1>Hello from StackMachine</h1>");',
        ]),
        "server.js": '\n'.join([
            '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));',
        ]),
    },
    env_vars=[{"name": "NODE_ENV", "value": "production", "sensitive": False}],
    on_upload_progress=lambda event: print("upload", event.percent),
)
app_version = deployment.wait(
    on_progress=lambda event: print(event.datetime, event.stream, event.message),
)
print(app_version.app.url)
```

### Watch builds

Save the build ID returned when a deployment starts. Use `client.deployments.retrieve` to inspect that existing build, including after your process restarts. This observes the build; it does not restart execution or create a new deployment.

```javascript
const buildId = "your-build-id";
const deployment = await client.deployments.retrieve(buildId);
// Should return: {
//   "buildId": "your-build-id",
//   "status": "RUNNING",
//   "appVersion": null
// }
console.log(deployment.buildId, deployment.status);
```

```python
build_id = "your-build-id"
deployment = client.deployments.retrieve(build_id)
# Should return: {
#   "build_id": "your-build-id",
#   "status": "RUNNING",
#   "app_version": null
# }
print(deployment.build_id, deployment.status)
```

### Wait for the watched build

Call `wait()` on the retrieved deployment to stream progress until it finishes. A successful build returns its app version; a failed build raises an error. To start a new build, create a new deployment.

```javascript
const appVersion = await deployment.wait({
  onProgress: ({ kind, message, datetime, stream }) => {
    console.log(datetime, stream, kind, message);
  },
});
// Should return: {
//   "id": "dv_xyz789",
//   "app": { "id": "da_abc123", "url": "https://my-app.stackmachine.app" }
// }
console.log(appVersion.id, appVersion.app.url);
```

```python
app_version = deployment.wait(
    on_progress=lambda e: print(e.datetime, e.stream, e.kind, e.message),
)
# Should return: {
#   "id": "dv_xyz789",
#   "app": { "url": "https://my-app.stackmachine.app" }
# }
print(app_version.id, app_version.app.url)
```

## Related docs

- [Deploy from files](/apps/deployments/from-files)
- [Deploy from ZIP](/apps/deployments/from-zip)

> Source: [stackmachine/sdks](https://github.com/stackmachine/sdks/tree/main/js) JavaScript examples.

Source: https://docs.stackmachine.com/apps/deployments/builds/index.mdx