Serverless S3 Cleaner Plugin

2.0.2 · active · verified Sun Apr 19

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.

Common errors

```
Cannot find module 'serverless-s3-cleaner'
```
cause 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: ...)
```
cause 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: ...)
```
cause 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`.

Warnings

breaking Version 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.
gotcha The 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.
gotcha If `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`.
breaking Version 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.

Install

npm install serverless-s3-cleaner npm
yarn add serverless-s3-cleaner yarn
pnpm add serverless-s3-cleaner pnpm

Imports

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)
wrong:
```
custom:
  s3Cleaner:
    # incorrect key
```
correct:
```
custom:
  serverless-s3-cleaner:
    # plugin specific options
```
All plugin-specific configuration options, such as `prompt`, `buckets`, and `bucketsToCleanOnDeploy`, must be nested under `custom.serverless-s3-cleaner`.
buckets (on stack removal)
wrong:
```
custom:
  serverless-s3-cleaner:
    buckets: ["your-bucket-name"]
```
correct:
```
custom:
  serverless-s3-cleaner:
    buckets:
      - your-bucket-name-1
      - your-bucket-name-2
```
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.

Quickstart

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

view raw JSON →