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

# JavaScript SDK: upload and commit files

> Create applications from a zip with apps.create() and send files to an existing application with apps.commit(), from a path, a Blob or bytes.

Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `appId` is the id of one of your apps: [`api.account.me()`](/en/sdks/js/client#account) lists them.

## Accepted inputs

`apps.create()` and `apps.commit()` take:

| Input | Where | Notes |
| - | - | - |
| A file path (`string`) | Node.js, Deno, Bun | Opened with `fs.openAsBlob` and streamed from disk, never read into memory |
| `Blob` / `File` | Everywhere | The name of a `File` is used as the filename |
| `Uint8Array` (or `Buffer`) | Everywhere | |

On edge runtimes and in the browser, pass a `Blob`, `File` or `Uint8Array`: a path only works where `node:fs` exists.

Uploads are **limited to 100 MB**. A larger file fails locally with `FILE_TOO_LARGE` (status `0`) before anything is sent. Uploads are streamed and have **no timeout**: pass a `signal` to cancel one.

## Creating an application

`apps.create(file)` deploys a `.zip` that contains a [`squarecloud.app`](/en/getting-started/config-file) configuration file at its root.

```typescript theme={"system"}
const app = await api.apps.create("./bot.zip");

console.log(app.id, app.name, app.ram, app.cpu, app.language.name, app.language.version);
console.log(app.domain);  // "<subdomain>.squareweb.app" for web apps, absent otherwise
console.log(app.cluster); // the cluster the app was placed on
```

| Field | Description |
| - | - |
| `id` | The new app's id |
| `name` | Name from the config file |
| `description` | Present only when set |
| `domain` | Full `<subdomain>.squareweb.app` host; absent for non-web apps |
| `cluster` | Cluster the app was placed on |
| `ram` / `cpu` | Allocated resources |
| `language` | `{ name, version }` |

## Committing to an application

`apps.commit(appId, file, { path, filename, signal })` uploads a file into an existing app:

* A `.zip` is **unpacked** at `path` (the app root by default).
* Any other file lands at `path/<filename>`.

The filename is `filename`, else the file's own name (path or `File`), else `commit.zip`.

```typescript theme={"system"}
// Unpack a zip at the root
await api.apps.commit(appId, "./build.zip");

// Unpack a zip into /src
await api.apps.commit(appId, "./patch.zip", { path: "/src" });

// A single file from memory: /src/index.js
await api.apps.commit(appId, new Blob([code]), { path: "/src", filename: "index.js" });
```

A commit does not restart the app. Call [`apps.restart()`](/en/sdks/js/managing_application#start-stop-and-restart) to apply it.

## Cancelling an upload

```typescript theme={"system"}
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 120_000);

try {
    await api.apps.create("./bot.zip", { signal: controller.signal });
} finally {
    clearTimeout(timer);
}
```

An aborted upload rejects with the signal's `reason`.

## Errors

| Status | Code | When |
| - | - | - |
| 0 | `FILE_TOO_LARGE` | The file is over 100 MB (checked locally) |
| 400 | `INVALID_FILE`, `INVALID_FILENAME` | No file, or a file name with path separators, `..` or control characters |
| 400 | `INVALID_PATH` | `path` contains traversal or shell metacharacters (commit) |
| 400 | `INSUFFICIENT_MEMORY` | Less than 256 MB of available memory on the plan (create) |
| 400 | `COMMIT_FAILED` | The commit could not be applied (commit) |
| 400 | `UPLOAD_FAILED`, `STORAGE_UPLOAD_FAILED`, `CLUSTER_SELECTION_FAILED` | The upload could not be processed (create) |
| 503 | `CLUSTER_MAINTENANCE_TRY_LATER` | Provisioning is paused for maintenance (create) |
| 503 | `UPLOAD_BUSY` | Too many uploads in progress: retried automatically |

A local path that cannot be opened throws the file system error, not a `SquareCloudAPIError`. See [Errors](/en/sdks/js/errors) for the full list.

## Next steps

<CardGroup cols={3}>
  <Card title="Managing files" icon="folder-open" href="/en/sdks/js/managing_files">
    List, read, write, move and delete app files.
  </Card>

  <Card title="Upload API reference" icon="code" href="/en/api-reference/endpoint/apps/upload">
    The REST endpoints behind these methods.
  </Card>

  <Card title="Upload from the CLI" icon="terminal" href="/en/cli-reference/deploy">
    The same actions from the terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.