Registry / aws / serverless-s3-cleaner

serverless-s3-cleaner

library2.0.2jsnpmunverified

serverless-s3-cleaner is a Serverless Framework plugin designed to manage the emptying of AWS S3 buckets as part of the stack deployment and removal lifecycle. It acts as a robust replacement for the unmaintained `serverless-s3-remover` plugin, addressing several limitations including support for emptying versioned buckets and improved console logging. The current stable version is 2.0.2, with releases typically driven by compatibility requirements with new Serverless Framework versions, such as the major update to v2.0.0 for Serverless Framework v3 logging API. Key differentiators include its ability to clean buckets not just on stack removal, but also prior to deployment (useful for renaming buckets), and comprehensive support for S3 bucket versioning, ensuring all object versions and delete markers are purged. It primarily functions through YAML configuration within `serverless.yml` and is tightly integrated with the Serverless Framework's CLI commands.

aws devops

npm install serverless-s3-cleaner

github ↗package ↗

INSTALL

IMPORT

SIG · SERVERLESS-S3-CLEA

serverless-s3-cleaner

awsjavascriptv2.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

serverless-s3-cleaner (plugin activation)

✓ plugins: - serverless-s3-cleaner

This specifies the plugin's activation within your `serverless.yml`. This is how the Serverless Framework loads the plugin; it is not a JavaScript/TypeScript module import.

custom.serverless-s3-cleaner (configuration block)

✓ custom: serverless-s3-cleaner: # plugin specific options

✗ custom: s3Cleaner: # incorrect key

All plugin-specific configuration options, such as `prompt`, `buckets`, and `bucketsToCleanOnDeploy`, must be nested under `custom.serverless-s3-cleaner`.

buckets (on stack removal)

✓ custom: serverless-s3-cleaner: buckets: - your-bucket-name-1 - your-bucket-name-2

✗ custom: serverless-s3-cleaner: buckets: ["your-bucket-name"]

The `buckets` array specifies S3 bucket names to be emptied when the Serverless stack is removed via `sls remove` or `sls s3remove`. Ensure valid YAML array syntax.

bucketsToCleanOnDeploy (on stack deployment)

✓ custom: serverless-s3-cleaner: bucketsToCleanOnDeploy: - old-bucket-to-empty-before-deploy

The `bucketsToCleanOnDeploy` array lists S3 buckets to be emptied before a new stack deployment (`sls deploy`). This is useful for clearing old bucket contents when renaming a resource to prevent CloudFormation errors.

This quickstart demonstrates the `serverless-s3-cleaner` plugin's configuration in `serverless.yml`. It shows how to activate the plugin, define buckets for cleanup on stack removal, and specify buckets to clean before deployment, including essential IAM permissions for S3 operations.

service: my-s3-cleanup-app provider: name: aws runtime: nodejs20.x # Or your preferred runtime region: us-east-1 # Ensure the IAM role used by Serverless for deployment has necessary S3 permissions. # This is a critical step to prevent deployment/removal failures. iam: role: statements: - Effect: "Allow" Action: - s3:ListBucket - s3:ListBucketVersions - s3:DeleteObject - s3:DeleteObjectVersion Resource: - "arn:aws:s3:::my-unique-data-bucket-${sls:stage}" - "arn:aws:s3:::my-unique-data-bucket-${sls:stage}/*" - "arn:aws:s3:::static-assets-old-name-${sls:stage}" - "arn:aws:s3:::static-assets-old-name-${sls:stage}/*" plugins: - serverless-s3-cleaner custom: serverless-s3-cleaner: # Set to 'true' to require confirmation before any bucket emptying operation. # Highly recommended for production environments to prevent accidental data loss. prompt: false # Buckets listed here will be emptied when you run 'sls remove' for this stack. buckets: - my-unique-data-bucket-${sls:stage} # Example: my-unique-data-bucket-dev # Buckets listed here will be emptied BEFORE 'sls deploy' runs for this stack. # Useful for cleaning up old buckets when you've renamed them in your stack definition. bucketsToCleanOnDeploy: - static-assets-old-name-${sls:stage} # This bucket will be cleaned on deploy. resources: Resources: MyDataBucket: Type: AWS::S3::Bucket Properties: BucketName: my-unique-data-bucket-${sls:stage} VersioningConfiguration: Status: Enabled # Versioned buckets are fully supported by this plugin. OldStaticAssetsBucket: Type: AWS::S3::Bucket Properties: BucketName: static-assets-old-name-${sls:stage} functions: exampleFunction: handler: handler.hello events: - httpApi: path: /hello method: get

Debug

Known issues

breakingVersion 2.0.0 introduced breaking changes, making it incompatible with Serverless Framework v2.x. Users must upgrade their Serverless Framework installation to v3.x or later to use `serverless-s3-cleaner` v2.0.0 and above.

fix

Upgrade Serverless Framework to version 3.x: `npm install -g serverless@latest` or `yarn global add serverless@latest`. Ensure your `serverless.yml` configuration is also compatible with Serverless v3.

affects: >=2.0.0

gotchaThe plugin requires specific IAM permissions (`s3:ListBucket`, `s3:ListBucketVersions`, `s3:DeleteObject`, `s3:DeleteObjectVersion`) for the IAM role used by Serverless. Missing these permissions will lead to `Access Denied` errors during cleanup operations.

fix

Ensure your Serverless provider's IAM role includes the necessary S3 permissions for all buckets listed in your plugin configuration. Refer to the README for exact permissions needed.

affects: >=1.0.0

gotchaIf `prompt: true` is configured, the plugin will require manual confirmation before emptying any S3 bucket. In CI/CD environments, this will cause deployments/removals to hang, leading to timeouts.

fix

For automated CI/CD pipelines, set `prompt: false` in your `serverless.yml` configuration for the `serverless-s3-cleaner` plugin. Example: `custom.serverless-s3-cleaner.prompt: false`.

affects: >=1.0.0

breakingVersion 2.0.0 migrated to the new logging API introduced in Serverless Framework v3. While this is an internal change, it reinforces the incompatibility with older Serverless Framework versions and may affect custom tooling that parses Serverless CLI output.

fix

Ensure Serverless Framework v3.x is used. Update any scripts or tools that might be parsing the raw CLI output of Serverless commands, as logging formats may have changed.

affects: >=2.0.0

Errors

Common errors & fixes

Cannot find module 'serverless-s3-cleaner'

The plugin is not correctly installed or not listed in `plugins` section of `serverless.yml`.

fix

Run `npm install serverless-s3-cleaner --save-dev` and ensure `serverless-s3-cleaner` is listed under the `plugins:` section in your `serverless.yml`.

An error occurred: [YourBucketName] - Access Denied (Service: Amazon S3; Status Code: 403; Error Code: AccessDenied; Request ID: ...)

The IAM role associated with your Serverless deployment lacks the necessary S3 permissions to list or delete objects/versions in the specified bucket.

fix

Add `s3:ListBucket`, `s3:ListBucketVersions`, `s3:DeleteObject`, and `s3:DeleteObjectVersion` permissions to the IAM role that your Serverless stack uses, targeting the specific S3 buckets configured for cleaning.

The specified bucket is not empty. (Service: Amazon S3; Status Code: 409; Error Code: BucketNotEmpty; Request ID: ...)

This error typically occurs during `sls remove` when CloudFormation attempts to delete an S3 bucket that still contains objects, indicating the plugin failed to empty it or was not configured to clean that specific bucket.

fix

Verify that the bucket is correctly listed under `custom.serverless-s3-cleaner.buckets` in your `serverless.yml`. Ensure the IAM role has all required S3 permissions and that `prompt: false` is set for non-interactive environments. Rerun `sls remove`.

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

serverlessrequiredPeer dependency, required for the plugin to function within the Serverless Framework environment.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/coyoteecd/serverless-s3-cleaner ↗

packagehttps://www.npmjs.com/package/serverless-s3-cleaner ↗