From 509143469a872e82ee0440402f2b48a282a6342c Mon Sep 17 00:00:00 2001 From: "ask-bonk[bot]" Date: Wed, 4 Mar 2026 09:57:33 +0000 Subject: [PATCH] Doc backup exclude options per SDK#437 Co-authored-by: whoiskatrin --- src/content/docs/sandbox/api/backups.mdx | 8 ++- .../docs/sandbox/guides/backup-restore.mdx | 61 +++++++++++++++++++ 2 files changed, 68 insertions(+), 1 deletion(-) diff --git a/src/content/docs/sandbox/api/backups.mdx b/src/content/docs/sandbox/api/backups.mdx index a33f70e65f2..d12c630990f 100644 --- a/src/content/docs/sandbox/api/backups.mdx +++ b/src/content/docs/sandbox/api/backups.mdx @@ -25,6 +25,8 @@ await sandbox.createBackup(options: BackupOptions): Promise - `dir` (required) - Absolute path to the directory to back up (for example, `"/workspace"`) - `name` (optional) - Human-readable name for the backup. Maximum 256 characters, no control characters. - `ttl` (optional) - Time-to-live in seconds until the backup expires. Default: `259200` (3 days). Must be a positive number. + - `exclude` (optional) - Array of file or directory patterns to exclude from the backup. Patterns are passed to `mksquashfs -ef` (one pattern per line). Common examples: `node_modules`, `.git`, `dist`, `*.log`. Must not contain control characters. + - `excludeDefaults` (optional) - When `true`, adds a default set of exclude patterns for common dependency and build directories: `node_modules`, `.git`, `dist`, `build`, `.next`, `.turbo`, `.cache`. Default: `false`. **Returns**: `Promise` containing: @@ -56,7 +58,7 @@ await sandbox.restoreBackup(backup); **Throws**: -- `InvalidBackupConfigError` - If `dir` is not absolute, contains `..`, the `BACKUP_BUCKET` binding is missing, or the R2 presigned URL credentials are not configured +- `InvalidBackupConfigError` - If `dir` is not absolute, contains `..`, the `BACKUP_BUCKET` binding is missing, the R2 presigned URL credentials are not configured, `exclude` contains non-string values or strings with control characters, or `excludeDefaults` is not a boolean - `BackupCreateError` - If the container fails to create the archive or the upload to R2 fails :::note[R2 binding and credentials required] @@ -195,6 +197,8 @@ interface BackupOptions { dir: string; name?: string; ttl?: number; + exclude?: string[]; + excludeDefaults?: boolean; } ``` @@ -203,6 +207,8 @@ interface BackupOptions { - `dir` (required) - Absolute path to the directory to back up - `name` (optional) - Human-readable backup name. Maximum 256 characters, no control characters. - `ttl` (optional) - Time-to-live in seconds. Default: `259200` (3 days). Must be a positive number. +- `exclude` (optional) - Array of file or directory patterns to exclude from the backup archive. Patterns are passed directly to `mksquashfs` via `-ef` (one pattern per line). Common examples: `node_modules`, `.git`, `dist`, `*.log`. Must not contain control characters. +- `excludeDefaults` (optional) - When `true`, prepends a default set of exclude patterns for common dependency and build directories: `node_modules`, `.git`, `dist`, `build`, `.next`, `.turbo`, `.cache`. Custom `exclude` patterns are appended after the defaults. Default: `false`. ### `DirectoryBackup` diff --git a/src/content/docs/sandbox/guides/backup-restore.mdx b/src/content/docs/sandbox/guides/backup-restore.mdx index adfecd1012a..3bc1c2987ab 100644 --- a/src/content/docs/sandbox/guides/backup-restore.mdx +++ b/src/content/docs/sandbox/guides/backup-restore.mdx @@ -96,6 +96,66 @@ console.log(`Backup created: ${backup.id}`); The SDK creates a compressed squashfs archive of the directory and uploads it directly to your R2 bucket using a presigned URL. +## Exclude files from backups + +By default, `createBackup()` includes every file and subdirectory in the target path. Use the `exclude` and `excludeDefaults` options to skip files you do not need in the archive, such as dependency directories and build output. This reduces archive size and speeds up both backup and restore operations. + +### Use default excludes + +Set `excludeDefaults: true` to skip common dependency and build directories automatically. The default exclude list is: `node_modules`, `.git`, `dist`, `build`, `.next`, `.turbo`, `.cache`. + + + +```ts +const sandbox = getSandbox(env.Sandbox, "my-sandbox"); + +const backup = await sandbox.createBackup({ + dir: "/workspace", + excludeDefaults: true, +}); +``` + + + +### Specify custom exclude patterns + +Use the `exclude` option to provide your own list of patterns. Patterns are passed to `mksquashfs -ef` (one pattern per line): + + + +```ts +const sandbox = getSandbox(env.Sandbox, "my-sandbox"); + +const backup = await sandbox.createBackup({ + dir: "/workspace", + exclude: ["node_modules", "*.log", ".env"], +}); +``` + + + +### Combine defaults with custom patterns + +You can use both options together. The default patterns are applied first, followed by your custom patterns: + + + +```ts +const sandbox = getSandbox(env.Sandbox, "my-sandbox"); + +const backup = await sandbox.createBackup({ + dir: "/workspace", + excludeDefaults: true, + exclude: ["*.log", "tmp", "coverage"], +}); +``` + + + +:::note +Exclude patterns must not contain control characters. The `exclude` option must be an array of strings, and `excludeDefaults` must be a boolean. Invalid values throw an `InvalidBackupConfigError`. +::: + ## Restore a backup Use `restoreBackup()` to restore a directory from a backup: @@ -415,6 +475,7 @@ This means `mksquashfs` could not read one or more files inside the directory yo - **Stop writes before restoring** - Stop processes writing to the target directory before calling `restoreBackup()` - **Use checkpoints** - Create backups before risky operations like package installations or migrations +- **Exclude unnecessary files** - Use `excludeDefaults: true` or the `exclude` option to skip dependency and build directories, reducing archive size and speeding up backup and restore operations - **Set appropriate TTLs** - Use short TTLs for temporary checkpoints and longer TTLs for persistent snapshots - **Store handles externally** - Persist `DirectoryBackup` handles to KV, D1, or Durable Object storage for cross-request access - **Configure R2 lifecycle rules** - Set up [object lifecycle rules](/r2/buckets/object-lifecycles/) to automatically delete expired backups from R2, since TTL is only enforced at restore time