Migrating to v4

Latest patch covered here: v4.0.1 (released 2026-05-30).

Requirements

Node.js 20.0.0 or newer (v3 supported Node 18)

Breaking changes summary

v3.x	v4.x
`client.users.*`	`client.user.*`
`app.backup` / `app.backups`	`app.snapshots`
`Backup` export	`Snapshot` export
`app.deploys.list()` returns flat `Deployment[]`	Returns `Deployment[][]` (call `.flat()` for old shape)
`Deployment.id` formatted as `git-${string}`	Plain commit SHA-1 (40 hex chars)
`app.network.dns()` returns an array	Returns `{ ownership, ssl }`
`app.network.analytics()` takes no arguments	Requires `{ start, end }` (ISO string or `Date`)
`app.network.purgeCache(paths?)`	`purgeCache()` — argument removed in v4.0.1, always purges the whole cache
`app.custom === undefined`	`app.custom === null`
`workspace.members` / `.applications` held data arrays	Renamed to `workspace.memberList` / `.applicationList`; the original names are now modules
`app.commit(file, name, restart)`	`app.commit(file, name)` — third argument removed
`app.files.create(content, fullPath)`	`app.files.create(content, fileName, path)`

Renames

`client.users` → `client.user`

// v3
await api.users.get();

// v4
await api.user.get();

api.users is still exported as a deprecated getter that proxies to api.user, but it prints a warning at runtime.

Backups → Snapshots

// v3
await app.backups.create();
await app.backup.list();

// v4
await app.snapshots.create();
await app.snapshots.list();

The Backup export is now a deprecated alias of Snapshot.

Application

`Application.custom`

app.custom is now null (was undefined in v3) when no custom domain is bound.

`app.commit(file, fileName, restart)`

The third restart argument has been removed. Restart manually after committing:

// v3
await app.commit(buffer, "index.js", true);

// v4
await app.commit(buffer, "index.js");
await app.restart();

`app.files.create(content, path)`

The signature is now create(content, fileName, path = "/"). Migrating:

// v3 — single combined path
await app.files.create(content, "./folder/test_file.txt");

// v4 — separate file name and directory
await app.files.create(content, "test_file.txt", "/folder");

Deploys

`app.deploys.list()` shape

// v3
const events: Deployment[] = await app.deploys.list();

// v4
const timelines: Deployment[][] = await app.deploys.list();
const events = timelines.flat(); // same shape as v3

`Deployment.id`

Now a plain commit SHA-1 (40 hex chars) instead of a `git-…` formatted string.

Network

`app.network.dns()`

// v3
const records: DnsRecord[] = await app.network.dns();

// v4
const { ownership, ssl } = await app.network.dns();

`app.network.analytics()`

// v3
const data = await app.network.analytics();

// v4 — { start, end } is now required (ISO string or Date)
const data = await app.network.analytics({
    start: new Date(Date.now() - 24 * 60 * 60 * 1000),
    end:   new Date(),
});

`app.network.purgeCache()`

// v3 and v4.0.0
await app.network.purgeCache(["/static/old.js"]);

// v4.0.1 and later — selective purge removed
await app.network.purgeCache();

Workspaces

// v3
workspace.members;      // raw member data
workspace.applications; // raw application data

// v4
workspace.memberList;        // raw member data
workspace.applicationList;   // raw application data
workspace.members.add(...);  // members module
workspace.applications.add(...); // applications module

What’s new in v4

Beyond the renames and signature changes above, v4 adds a substantial feature set:

Databases — full lifecycle, credentials, snapshots and metrics (Databases)
Workspaces — team collaboration with invite codes and roles (Workspaces)
Environment variables — list / set / replace / delete (Environment variables)
Application metrics — 24h CPU/RAM/network samples (Managing applications)
Real-time SSE stream — app.realtime() (Realtime)
Edge analytics — analytics, errors, logs and latency percentiles (Network)
GitHub App integration — app.deploys.linkGithubApp({ ... }) (Deploys)
Snapshot restore — app.snapshots.restore({ snapshotId, versionId }) and db.snapshots.restore(snapshotId, versionId)
Status-all endpoints — api.applications.statusAll(), api.databases.statusAll()
Service status — api.service.status()
User scoped snapshots — api.user.snapshots(scope)
New User fields — User.locale, User.createdAt, User.databases
New BaseApplication fields — domain, custom, createdAt
SquareCloudAPIError.code — public for switch-based error handling

Services

Runtimes

Platform

Troubleshooting

CLI

SDKs

Changelog

Requirements

Breaking changes summary

Renames

`client.users` → `client.user`

Backups → Snapshots

Application

`Application.custom`

`app.commit(file, fileName, restart)`

`app.files.create(content, path)`

Deploys

`app.deploys.list()` shape

`Deployment.id`

Network

`app.network.dns()`

`app.network.analytics()`

`app.network.purgeCache()`

Workspaces

What’s new in v4

​Requirements

​Breaking changes summary

​Renames

​client.users → client.user

​Backups → Snapshots

​Application

​Application.custom

​app.commit(file, fileName, restart)

​app.files.create(content, path)

​Deploys

​app.deploys.list() shape

​Deployment.id

​Network

​app.network.dns()

​app.network.analytics()

​app.network.purgeCache()

​Workspaces

​What’s new in v4

Requirements

Breaking changes summary

Renames

`client.users` → `client.user`

Backups → Snapshots

Application

`Application.custom`

`app.commit(file, fileName, restart)`

`app.files.create(content, path)`

Deploys

`app.deploys.list()` shape

`Deployment.id`

Network

`app.network.dns()`

`app.network.analytics()`

`app.network.purgeCache()`

Workspaces

What’s new in v4