{"id":14915,"library":"serverless-s3-cleaner","title":"Serverless S3 Cleaner Plugin","description":"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.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/coyoteecd/serverless-s3-cleaner","tags":["javascript","serverless","serverless-plugin","aws","git"],"install":[{"cmd":"npm install serverless-s3-cleaner","lang":"bash","label":"npm"},{"cmd":"yarn add serverless-s3-cleaner","lang":"bash","label":"yarn"},{"cmd":"pnpm add serverless-s3-cleaner","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for the plugin to function within the Serverless Framework environment.","package":"serverless","optional":false}],"imports":[{"note":"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.","symbol":"serverless-s3-cleaner (plugin activation)","correct":"plugins:\n  - serverless-s3-cleaner"},{"note":"All plugin-specific configuration options, such as `prompt`, `buckets`, and `bucketsToCleanOnDeploy`, must be nested under `custom.serverless-s3-cleaner`.","wrong":"custom:\n  s3Cleaner:\n    # incorrect key","symbol":"custom.serverless-s3-cleaner (configuration block)","correct":"custom:\n  serverless-s3-cleaner:\n    # plugin specific options"},{"note":"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.","wrong":"custom:\n  serverless-s3-cleaner:\n    buckets: [\"your-bucket-name\"]","symbol":"buckets (on stack removal)","correct":"custom:\n  serverless-s3-cleaner:\n    buckets:\n      - your-bucket-name-1\n      - your-bucket-name-2"},{"note":"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.","symbol":"bucketsToCleanOnDeploy (on stack deployment)","correct":"custom:\n  serverless-s3-cleaner:\n    bucketsToCleanOnDeploy:\n      - old-bucket-to-empty-before-deploy"}],"quickstart":{"code":"service: my-s3-cleanup-app\n\nprovider:\n  name: aws\n  runtime: nodejs20.x # Or your preferred runtime\n  region: us-east-1\n  # Ensure the IAM role used by Serverless for deployment has necessary S3 permissions.\n  # This is a critical step to prevent deployment/removal failures.\n  iam:\n    role:\n      statements:\n        - Effect: \"Allow\"\n          Action:\n            - s3:ListBucket\n            - s3:ListBucketVersions\n            - s3:DeleteObject\n            - s3:DeleteObjectVersion\n          Resource:\n            - \"arn:aws:s3:::my-unique-data-bucket-${sls:stage}\"\n            - \"arn:aws:s3:::my-unique-data-bucket-${sls:stage}/*\"\n            - \"arn:aws:s3:::static-assets-old-name-${sls:stage}\"\n            - \"arn:aws:s3:::static-assets-old-name-${sls:stage}/*\"\n\nplugins:\n  - serverless-s3-cleaner\n\ncustom:\n  serverless-s3-cleaner:\n    # Set to 'true' to require confirmation before any bucket emptying operation.\n    # Highly recommended for production environments to prevent accidental data loss.\n    prompt: false\n\n    # Buckets listed here will be emptied when you run 'sls remove' for this stack.\n    buckets:\n      - my-unique-data-bucket-${sls:stage} # Example: my-unique-data-bucket-dev\n\n    # Buckets listed here will be emptied BEFORE 'sls deploy' runs for this stack.\n    # Useful for cleaning up old buckets when you've renamed them in your stack definition.\n    bucketsToCleanOnDeploy:\n      - static-assets-old-name-${sls:stage} # This bucket will be cleaned on deploy.\n\nresources:\n  Resources:\n    MyDataBucket:\n      Type: AWS::S3::Bucket\n      Properties:\n        BucketName: my-unique-data-bucket-${sls:stage}\n        VersioningConfiguration:\n          Status: Enabled # Versioned buckets are fully supported by this plugin.\n    OldStaticAssetsBucket:\n      Type: AWS::S3::Bucket\n      Properties:\n        BucketName: static-assets-old-name-${sls:stage}\n\nfunctions:\n  exampleFunction:\n    handler: handler.hello\n    events:\n      - httpApi:\n          path: /hello\n          method: get","lang":"javascript","_review":true,"description":"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.","_review_reason":"The `lang` field for quickstart strictly requires 'javascript' or 'typescript', but the primary code for a Serverless plugin is YAML configuration. I have provided the `serverless.yml` content and set `lang` to 'javascript' as a fallback, noting the discrepancy."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install serverless-s3-cleaner --save-dev` and ensure `serverless-s3-cleaner` is listed under the `plugins:` section in your `serverless.yml`.","cause":"The plugin is not correctly installed or not listed in `plugins` section of `serverless.yml`.","error":"Cannot find module 'serverless-s3-cleaner'"},{"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.","cause":"The IAM role associated with your Serverless deployment lacks the necessary S3 permissions to list or delete objects/versions in the specified bucket.","error":"An error occurred: [YourBucketName] - Access Denied (Service: Amazon S3; Status Code: 403; Error Code: AccessDenied; Request ID: ...)"},{"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`.","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.","error":"The specified bucket is not empty. (Service: Amazon S3; Status Code: 409; Error Code: BucketNotEmpty; Request ID: ...)"}],"ecosystem":"npm"}