Doc backup exclude options per SDK#437

src/content/docs/sandbox/api/backups.mdx

@@ -25,6 +25,8 @@ await sandbox.createBackup(options: BackupOptions): Promise<DirectoryBackup>
   - `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<DirectoryBackup>` 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`
 

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`.
+
+<TypeScriptExample>
+
+```ts
+const sandbox = getSandbox(env.Sandbox, "my-sandbox");
+
+const backup = await sandbox.createBackup({
+	dir: "/workspace",
+	excludeDefaults: true,
+});
+```
+
+</TypeScriptExample>
+
+### 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):
+
+<TypeScriptExample>
+
+```ts
+const sandbox = getSandbox(env.Sandbox, "my-sandbox");
+
+const backup = await sandbox.createBackup({
+	dir: "/workspace",
+	exclude: ["node_modules", "*.log", ".env"],
+});
+```
+
+</TypeScriptExample>
+
+### Combine defaults with custom patterns
+
+You can use both options together. The default patterns are applied first, followed by your custom patterns:
+
+<TypeScriptExample>
+
+```ts
+const sandbox = getSandbox(env.Sandbox, "my-sandbox");
+
+const backup = await sandbox.createBackup({
+	dir: "/workspace",
+	excludeDefaults: true,
+	exclude: ["*.log", "tmp", "coverage"],
+});
+```
+
+</TypeScriptExample>
+
+:::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