JavaScript SDK: upload and commit files

Examples use the api client from Creating the client. appId is the id of one of your apps: api.account.me() 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 configuration file at its root.

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.

// 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() to apply it.

Cancelling an upload

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 for the full list.

Next steps

Managing files

List, read, write, move and delete app files.

Upload API reference

The REST endpoints behind these methods.

Upload from the CLI

The same actions from the terminal.

CLI

VS Code

SDKs

JavaScript SDK: upload and commit files

Accepted inputs

Creating an application

Committing to an application

Cancelling an upload

Errors

Next steps

Managing files

Upload API reference

Upload from the CLI

​Accepted inputs

​Creating an application

​Committing to an application

​Cancelling an upload

​Errors

​Next steps

Managing files

Upload API reference

Upload from the CLI

Accepted inputs

Creating an application

Committing to an application

Cancelling an upload

Errors

Next steps