{"id":15935,"library":"webpack-s3-plugin","title":"Webpack S3 Plugin","description":"The `webpack-s3-plugin` is a specialized Webpack plugin designed to streamline the process of uploading compiled assets from a Webpack build directly to an Amazon S3 bucket. It is currently in a release candidate phase, indicated by version `1.2.0-rc.0`, suggesting ongoing development towards a stable 1.2.0 release. The plugin integrates deeply into the Webpack compilation lifecycle, allowing developers to define precise `include` or `exclude` rules, which can be regular expressions, functions, or arrays of rules, to control which assets are uploaded. It provides extensive configuration options for AWS S3, including credential management, region specification, and S3 object upload parameters like `ACL`. A key differentiator is its focus on handling assets directly from the build output, rather than reading from a local directory post-compilation, for efficiency. It requires `webpack` version 5 or higher as a peer dependency.","status":"active","version":"1.2.0-rc.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/webpack-contrib/s3-plugin-webpack","tags":["javascript","s3","webpack","node","upload","production"],"install":[{"cmd":"npm install webpack-s3-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add webpack-s3-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add webpack-s3-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for the plugin to integrate with Webpack's build system.","package":"webpack","optional":false}],"imports":[{"note":"While CommonJS `require` works, ESM `import` is the idiomatic approach in modern Webpack/Node.js projects, especially with TypeScript.","wrong":"const S3Plugin = require('webpack-s3-plugin');","symbol":"S3Plugin","correct":"import S3Plugin from 'webpack-s3-plugin';"},{"note":"This CommonJS import is typically used in older Node.js environments or Webpack configuration files that do not support ESM natively without transpilation.","symbol":"S3Plugin","correct":"const S3Plugin = require('webpack-s3-plugin');"},{"note":"Webpack configuration files typically expect a default export for the configuration object, which is where the plugin instance is defined.","wrong":"export const config = { plugins: [new S3Plugin({...})] };","symbol":"S3Plugin","correct":"export default { plugins: [new S3Plugin({...})] };"}],"quickstart":{"code":"import path from 'path';\nimport S3Plugin from 'webpack-s3-plugin';\nimport type { Configuration } from 'webpack';\n\nconst config: Configuration = {\n  mode: 'production',\n  entry: './src/index.js',\n  output: {\n    filename: 'bundle.js',\n    path: path.resolve(__dirname, 'dist'),\n    publicPath: 'https://my-bucket.s3.amazonaws.com/'\n  },\n  plugins: [\n    new S3Plugin({\n      // Only upload JavaScript and CSS files for the production build\n      include: /\\.(js|css)$/,\n      // Exclude source maps to keep bucket cleaner (optional)\n      exclude: /\\.map$/,\n      // s3Options are mandatory for AWS credentials and region\n      s3Options: {\n        accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',\n        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '',\n        region: process.env.AWS_REGION ?? 'us-east-1'\n      },\n      // s3UploadOptions define properties for uploaded objects\n      s3UploadOptions: {\n        Bucket: process.env.AWS_S3_BUCKET_NAME ?? 'my-webpack-assets-bucket',\n        // Override default 'public-read' ACL if needed (e.g., for private assets)\n        ACL: 'private'\n      },\n      // Optionally, configure cdnizer for asset URL rewriting\n      cdnizerOptions: {\n        defaultCDNBase: 'https://cdn.example.com'\n      }\n    })\n  ]\n};\n\nexport default config;\n","lang":"typescript","description":"This quickstart demonstrates configuring `webpack-s3-plugin` to upload bundled JavaScript and CSS files to a specified S3 bucket. It includes essential S3 authentication and region settings, shows how to define include/exclude rules, and overrides the default ACL to 'private' for enhanced security, leveraging environment variables for sensitive credentials."},"warnings":[{"fix":"Remove the `directory` option from your `S3Plugin` configuration when uploading Webpack build output.","message":"Do not set the `directory` option if you intend to upload files generated by your Webpack build process. Setting `directory` will cause the plugin to read files from the filesystem after compilation instead of directly using the assets from the Webpack output, leading to redundant I/O operations and potential inconsistencies. The plugin automatically handles build assets.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"In your `S3Plugin` configuration, set `s3UploadOptions: { ACL: 'private' }` or another appropriate ACL value based on your security requirements.","message":"By default, `s3UploadOptions` sets `ACL: 'public-read'` for uploaded objects. This grants read access to all internet users. If your assets contain sensitive information or should not be publicly accessible, you must explicitly override this default to a more restrictive ACL, such as `private`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consider waiting for a stable release (e.g., 1.2.0) for production deployments if maximum stability is critical. Always pin to exact versions in `package.json`.","message":"The current version, `1.2.0-rc.0`, is a release candidate. While generally stable, 'rc' versions may contain minor bugs or introduce breaking changes before the final stable release. It's recommended to test thoroughly in non-production environments.","severity":"gotcha","affected_versions":"1.2.0-rc.0"},{"fix":"Verify `s3Options` values are correct. Ensure `process.env.AWS_ACCESS_KEY_ID` and `process.env.AWS_SECRET_ACCESS_KEY` are set in your environment. Check AWS IAM policies for necessary S3 permissions. Using `AWS.SharedIniFileCredentials` for profiles is also an option.","message":"AWS credentials must be configured correctly. Common issues include missing `accessKeyId`, `secretAccessKey`, incorrect `region`, or insufficient IAM permissions on the AWS user/role accessing the S3 bucket. Ensure your AWS credentials have `s3:PutObject` and `s3:PutObjectAcl` permissions for the target bucket.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Provide a valid `s3Options` object with `accessKeyId`, `secretAccessKey`, and `region` (or `credentials` object) to the `S3Plugin` constructor.","cause":"The `s3Options` object, containing AWS credentials and region, was omitted or left empty in the plugin configuration.","error":"The s3Options are required"},{"fix":"Review the IAM policy attached to your AWS user or role and ensure it explicitly grants permissions for `s3:PutObject` and `s3:PutObjectAcl` on the target S3 bucket and objects within it.","cause":"The configured AWS credentials lack the necessary permissions to perform upload operations (e.g., `s3:PutObject`, `s3:PutObjectAcl`) on the specified S3 bucket.","error":"Error: Access Denied (StatusCode: 403)"},{"fix":"Verify that your `include` and `exclude` regular expressions or functions correctly match the filenames of the assets you intend to upload. Double-check the `Bucket` name in `s3UploadOptions`.","cause":"This often occurs if the `include` or `exclude` rules in the plugin configuration are too restrictive, preventing any compiled assets from matching for upload, or if `s3UploadOptions.Bucket` is incorrect.","error":"Webpack compilation successful, but no files uploaded to S3."}],"ecosystem":"npm"}