Registry / aws / webpack-s3-plugin

webpack-s3-plugin

library1.2.0-rc.0jsnpmunverified

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.

aws devops

npm install webpack-s3-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · WEBPACK-S3-PLUGIN

webpack-s3-plugin

awsjavascriptv1.2.0-rc.0

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.

S3Plugin

✓ import S3Plugin from 'webpack-s3-plugin';

✗ const S3Plugin = require('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

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

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

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

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;

Debug

Known issues

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: 1.2.0-rc.0

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

affects: >=1.0.0

Errors

Common errors & fixes

The s3Options are required

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)

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.

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

Upgrade

Version history

1.2.0-rc.0latest on npm

Audit

Dependencies

webpackrequiredPeer dependency required for the plugin to integrate with Webpack's build system.

Agent activity

35 hits · last 30 days

node

Resources

githubhttps://github.com/webpack-contrib/s3-plugin-webpack ↗

packagehttps://www.npmjs.com/package/webpack-s3-plugin ↗