Migration zu v4

Neuester hier behandelter Patch: v4.0.1 (veröffentlicht am 2026-05-30).

Anforderungen

Node.js 20.0.0 oder neuer (v3 unterstützte Node 18)

Zusammenfassung der Breaking Changes

v3.x	v4.x
`client.users.*`	`client.user.*`
`app.backup` / `app.backups`	`app.snapshots`
`Backup`-Export	`Snapshot`-Export
`app.deploys.list()` liefert flaches `Deployment[]`	Liefert `Deployment[][]` (`.flat()` aufrufen für die alte Form)
`Deployment.id` formatiert als `git-${string}`	Reines Commit-SHA-1 (40 Hex-Zeichen)
`app.network.dns()` liefert ein Array	Liefert `{ ownership, ssl }`
`app.network.analytics()` nimmt keine Argumente	Erfordert `{ start, end }` (ISO-String oder `Date`)
`app.network.purgeCache(paths?)`	`purgeCache()` — Argument in v4.0.1 entfernt, leert immer den gesamten Cache
`app.custom === undefined`	`app.custom === null`
`workspace.members` / `.applications` enthielten Daten-Arrays	Umbenannt zu `workspace.memberList` / `.applicationList`; die ursprünglichen Namen sind nun Module
`app.commit(file, name, restart)`	`app.commit(file, name)` — drittes Argument entfernt
`app.files.create(content, fullPath)`	`app.files.create(content, fileName, path)`

Umbenennungen

`client.users` → `client.user`

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

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

api.users wird weiterhin als veralteter Getter exportiert, der an api.user weiterleitet, gibt aber zur Laufzeit eine Warnung aus.

Backups → Snapshots

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

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

Der Backup-Export ist nun ein veralteter Alias von Snapshot.

Application

`Application.custom`

app.custom ist nun null (war in v3 undefined), wenn keine Custom-Domain gebunden ist.

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

Das dritte Argument restart wurde entfernt. Starte nach dem Commit manuell neu:

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

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

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

Die Signatur lautet nun create(content, fileName, path = "/"). Migration:

// v3 — einzelner kombinierter Pfad
await app.files.create(content, "./folder/test_file.txt");

// v4 — getrennter Dateiname und Verzeichnis
await app.files.create(content, "test_file.txt", "/folder");

Deploys

Form von `app.deploys.list()`

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

// v4
const timelines: Deployment[][] = await app.deploys.list();
const events = timelines.flat(); // gleiche Form wie v3

`Deployment.id`

Nun ein reines Commit-SHA-1 (40 Hex-Zeichen) anstelle eines `git-…`-formatierten Strings.

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 } ist nun erforderlich (ISO-String oder Date)
const data = await app.network.analytics({
    start: new Date(Date.now() - 24 * 60 * 60 * 1000),
    end:   new Date(),
});

`app.network.purgeCache()`

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

// v4.0.1 und später — selektives Leeren entfernt
await app.network.purgeCache();

Workspaces

// v3
workspace.members;      // rohe Mitgliederdaten
workspace.applications; // rohe Anwendungsdaten

// v4
workspace.memberList;        // rohe Mitgliederdaten
workspace.applicationList;   // rohe Anwendungsdaten
workspace.members.add(...);  // members-Modul
workspace.applications.add(...); // applications-Modul

Was ist neu in v4

Über die obigen Umbenennungen und Signaturänderungen hinaus bringt v4 eine umfangreiche Feature-Palette:

Datenbanken — vollständiger Lebenszyklus, Anmeldedaten, Snapshots und Metriken (Datenbanken)
Workspaces — Team-Zusammenarbeit mit Einladungscodes und Rollen (Workspaces)
Umgebungsvariablen — auflisten / setzen / ersetzen / löschen (Umgebungsvariablen)
Anwendungsmetriken — 24h-Stichproben von CPU/RAM/Netzwerk (Anwendungen verwalten)
Echtzeit-SSE-Stream — app.realtime() (Realtime)
Edge-Analytics — Analytics, Fehler, Logs und Latenz-Perzentile (Network)
GitHub-App-Integration — app.deploys.linkGithubApp({ ... }) (Deploys)
Snapshot-Wiederherstellung — app.snapshots.restore({ snapshotId, versionId }) und db.snapshots.restore(snapshotId, versionId)
Status-all-Endpoints — api.applications.statusAll(), api.databases.statusAll()
Service-Status — api.service.status()
Benutzerbezogene Snapshots — api.user.snapshots(scope)
Neue User-Felder — User.locale, User.createdAt, User.databases
Neue BaseApplication-Felder — domain, custom, createdAt
SquareCloudAPIError.code — öffentlich für switch-basierte Fehlerbehandlung

Dienste

Runtimes

Plattform

Fehlerbehebung

CLI

SDKs

Changelog

Anforderungen

Zusammenfassung der Breaking Changes

Umbenennungen

`client.users` → `client.user`

Backups → Snapshots

Application

`Application.custom`

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

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

Deploys

Form von `app.deploys.list()`

`Deployment.id`

Network

`app.network.dns()`

`app.network.analytics()`

`app.network.purgeCache()`

Workspaces

Was ist neu in v4

​Anforderungen

​Zusammenfassung der Breaking Changes

​Umbenennungen

​client.users → client.user

​Backups → Snapshots

​Application

​Application.custom

​app.commit(file, fileName, restart)

​app.files.create(content, path)

​Deploys

​Form von app.deploys.list()

​Deployment.id

​Network

​app.network.dns()

​app.network.analytics()

​app.network.purgeCache()

​Workspaces

​Was ist neu in v4

Anforderungen

Zusammenfassung der Breaking Changes

Umbenennungen

`client.users` → `client.user`

Backups → Snapshots

Application

`Application.custom`

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

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

Deploys

Form von `app.deploys.list()`

`Deployment.id`

Network

`app.network.dns()`

`app.network.analytics()`

`app.network.purgeCache()`

Workspaces

Was ist neu in v4