JavaScript SDK: app file manager

The file manager lives on api.apps.files. Every method takes the app id first, then a path inside the app. Paths are at most 256 characters. Examples use the api client from Creating the client. appId is the id of one of your apps: api.account.me() lists them.

Listing a directory

files.list(appId, path?) lists a directory (the app root when path is omitted).

for (const entry of await api.apps.files.list(appId, "/src")) {
    console.log(entry.type, entry.name, entry.size, entry.lastModified);
}

Field	Type	Description
`name`	`string`	Entry name
`type`	`"file" \| "directory"`	Entry kind
`size`	`number?`	Size in bytes. Absent on some directory entries
`lastModified`	`number \| null?`	Unix ms (may carry a fraction); `null` when unreadable

A directory that does not exist is 404 FILE_NOT_FOUND. A path the file manager does not expose is 403 BLOCKED_PATH.

Reading a file

files.read(appId, path) returns the file’s bytes as a Uint8Array. Files are limited to 10 MB: a larger one is 413 FILE_TOO_LARGE.

const bytes = await api.apps.files.read(appId, "/config.json");
const text = new TextDecoder().decode(bytes);

console.log(JSON.parse(text));

Writing a file

files.write(appId, path, content, { signal }) creates or overwrites a file.

A string is sent as plain text.
A Uint8Array is sent as base64, so any binary content round-trips.
Empty content ("" or empty bytes) creates an empty file.

// Text
await api.apps.files.write(appId, "/config.json", JSON.stringify({ debug: false }));

// Binary
const image = new Uint8Array(await (await fetch(imageUrl)).arrayBuffer());
await api.apps.files.write(appId, "/assets/logo.png", image);

Content over 10 MB fails locally with FILE_TOO_LARGE (status 0) before anything is sent. Content over 1 MiB is sent without a timeout, like an upload: pass { signal } to cancel it. For larger files, use apps.commit().

Writing does not restart the app. Call apps.restart() to apply the change.

Moving or renaming a file

await api.apps.files.move(appId, "/config.json", "/config.old.json");

Deleting a file

await api.apps.files.delete(appId, "/config.old.json");

Errors

Status	Code	When
0	`FILE_TOO_LARGE`	`write` content over 10 MB (checked locally)
400	`INVALID_PATH`	The path fails validation (traversal, invalid characters, too long), or `move` to the same path
400	`DELETE_FAILED`, `RENAME_FAILED`	The cluster could not delete or rename the file
403	`BLOCKED_PATH`	The path is not exposed by the file manager
403	`PERMISSION_DENIED`	Your workspace role cannot touch a restricted file (such as `.env`)
404	`FILE_NOT_FOUND`	The file or directory does not exist
413	`FILE_TOO_LARGE`	`read` of a file over 10 MB
429	`KEEP_CALM`	More than 10 writes in 5 seconds

See Errors for the codes every call can return.

Next steps

Environment variables

Read and change the variables of an app.

File manager API reference

The REST endpoints behind these methods.

Manage files from the CLI

The same actions from the terminal.

CLI

VS Code

SDKs

JavaScript SDK: app file manager

Listing a directory

Reading a file

Writing a file

Moving or renaming a file

Deleting a file

Errors

Next steps

Environment variables

File manager API reference

Manage files from the CLI

​Listing a directory

​Reading a file

​Writing a file

​Moving or renaming a file

​Deleting a file

​Errors

​Next steps

Environment variables

File manager API reference

Manage files from the CLI

Listing a directory

Reading a file

Writing a file

Moving or renaming a file

Deleting a file

Errors

Next steps