Skip to content

docs(storage): add keepOnDelete to defineStorage() #8548

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
adrianjoshua-strutt wants to merge 3 commits into
base: main
Choose a base branch
from
+29 −0
Open

docs(storage): add keepOnDelete to defineStorage() #8548

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
29af69f
docs(storage): add removalPolicy configuration to defineStorage()
adrianjoshua-strutt Apr 8, 2026
32089e8
address review feedback: document both values, add cost warning, clar…
adrianjoshua-strutt Apr 8, 2026
6aadf7e
rename removalPolicy to keepOnDelete in docs
adrianjoshua-strutt Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions src/pages/[platform]/build-a-backend/storage/set-up-storage/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -411,6 +411,35 @@ try {
```
</InlineFilter>

## Configure storage deletion behavior

By default, Amplify deletes the S3 bucket and all its objects when you remove the storage resource or delete your Amplify app. To preserve the bucket and its data, set `keepOnDelete` to `true`:

```ts title="amplify/storage/resource.ts"
export const storage = defineStorage({
name: 'myProjectFiles',
// Keep the bucket when the resource is removed
keepOnDelete: true,
});
```

| Setting | Behavior |
| --- | --- |
| `keepOnDelete: false` (default) | The bucket and all objects are deleted on removal. |
| `keepOnDelete: true` | The bucket is preserved on removal. You must delete it manually when no longer needed. |

<Callout warning>

Retained buckets continue to incur S3 storage costs. To avoid unexpected charges, delete retained buckets manually through the [AWS S3 console](https://console.aws.amazon.com/s3/) or the AWS CLI (replace `your-bucket-name`: `aws s3 rb s3://your-bucket-name --force`) when they are no longer needed.

</Callout>

<Callout info>

When using `npx ampx sandbox`, the bucket is always deleted regardless of the `keepOnDelete` setting. This prevents resource accumulation during development. The `keepOnDelete` setting only takes effect in deployed environments (connected Git branches).

</Callout>

## Connect your app code to the storage backend

The Amplify Storage library provides client APIs that connect to the backend resources you defined.
Expand Down
Loading