Webpack S3 Plugin

Common errors

• The s3Options are required

  cause The `s3Options` object, containing AWS credentials and region, was omitted or left empty in the plugin configuration.
  fix Provide a valid `s3Options` object with `accessKeyId`, `secretAccessKey`, and `region` (or `credentials` object) to the `S3Plugin` constructor.

• Error: Access Denied (StatusCode: 403)

  cause The configured AWS credentials lack the necessary permissions to perform upload operations (e.g., `s3:PutObject`, `s3:PutObjectAcl`) on the specified S3 bucket.
  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.

• Webpack compilation successful, but no files uploaded to S3.

  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.
  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`.

Warnings

• gotcha 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.
  Fix: Remove the `directory` option from your `S3Plugin` configuration when uploading Webpack build output.
• gotcha 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`.
  Fix: In your `S3Plugin` configuration, set `s3UploadOptions: { ACL: 'private' }` or another appropriate ACL value based on your security requirements.
• gotcha 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.
  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`.
• gotcha 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.
  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.

Install

• npm install webpack-s3-plugin npm
• yarn add webpack-s3-plugin yarn
• pnpm add webpack-s3-plugin pnpm

Imports

• S3Plugin
  wrong:

  const S3Plugin = require('webpack-s3-plugin');

  correct:

  import S3Plugin from 'webpack-s3-plugin';

  While CommonJS `require` works, ESM `import` is the idiomatic approach in modern Webpack/Node.js projects, especially with TypeScript.
• S3Plugin

  const S3Plugin = require('webpack-s3-plugin');

  This CommonJS import is typically used in older Node.js environments or Webpack configuration files that do not support ESM natively without transpilation.
• S3Plugin
  wrong:

  export const config = { plugins: [new S3Plugin({...})] };

  correct:

  export default { plugins: [new S3Plugin({...})] };

  Webpack configuration files typically expect a default export for the configuration object, which is where the plugin instance is defined.

Quickstart

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.

import path from 'path';
import S3Plugin from 'webpack-s3-plugin';
import type { Configuration } from 'webpack';

const config: Configuration = {
  mode: 'production',
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
    publicPath: 'https://my-bucket.s3.amazonaws.com/'
  },
  plugins: [
    new S3Plugin({
      // Only upload JavaScript and CSS files for the production build
      include: /\.(js|css)$/,
      // Exclude source maps to keep bucket cleaner (optional)
      exclude: /\.map$/,
      // s3Options are mandatory for AWS credentials and region
      s3Options: {
        accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '',
        region: process.env.AWS_REGION ?? 'us-east-1'
      },
      // s3UploadOptions define properties for uploaded objects
      s3UploadOptions: {
        Bucket: process.env.AWS_S3_BUCKET_NAME ?? 'my-webpack-assets-bucket',
        // Override default 'public-read' ACL if needed (e.g., for private assets)
        ACL: 'private'
      },
      // Optionally, configure cdnizer for asset URL rewriting
      cdnizerOptions: {
        defaultCDNBase: 'https://cdn.example.com'
      }
    })
  ]
};

export default config;