Rspack S3 Plugin

Uploads compiled assets to Amazon S3 after Rspack build. This plugin is a Rspack version of the popular webpack-s3-plugin.

Features

• ✅ Uploads build assets to S3 automatically after compilation
• ✅ Supports file inclusion/exclusion patterns
• ✅ CloudFront invalidation support
• ✅ Progress indicators during upload
• ✅ CDN URL replacement (cdnizer integration)
• ✅ Priority-based upload ordering
• ✅ Dynamic upload options
• ✅ Built specifically for Rspack

Installation

pnpm add -D rspack-s3-plugin
# or
npm install --save-dev rspack-s3-plugin
# or
yarn add -D rspack-s3-plugin

Requirements

• Node.js >= 14.0.0
• Rspack >= 0.1.0

Usage

Basic Example

const S3Plugin = require("rspack-s3-plugin");

module.exports = {
  // ... your rspack config
  plugins: [
    new S3Plugin({
      s3Options: {
        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
        region: "us-west-1",
      },
      s3UploadOptions: {
        Bucket: "my-bucket-name",
      },
    }),
  ],
};

With Include/Exclude

new S3Plugin({
  // Only upload CSS and JS files
  include: /.*\.(css|js)$/,
  // Exclude HTML files
  exclude: /.*\.html$/,
  s3Options: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
  s3UploadOptions: {
    Bucket: 'my-bucket-name',
  },
}),

With CloudFront Invalidation

new S3Plugin({
  s3Options: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    sessionToken: process.env.AWS_SESSION_TOKEN, // optional
  },
  s3UploadOptions: {
    Bucket: 'my-bucket-name',
  },
  cloudfrontInvalidateOptions: {
    DistributionId: process.env.CLOUDFRONT_DISTRIBUTION_ID,
    Items: ['/*'],
  },
}),

With Base Path

new S3Plugin({
  basePath: 'assets/',
  s3Options: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
  s3UploadOptions: {
    Bucket: 'my-bucket-name',
  },
}),

With Dynamic Base Path Transform

new S3Plugin({
  basePathTransform: async () => {
    // Return a promise or string
    const gitSha = require('child_process')
      .execSync('git rev-parse --short HEAD')
      .toString()
      .trim();
    return `v${gitSha}/`;
  },
  s3Options: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
  s3UploadOptions: {
    Bucket: 'my-bucket-name',
  },
}),

With CDN URL Replacement

new S3Plugin({
  s3Options: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
  s3UploadOptions: {
    Bucket: 'my-bucket-name',
  },
  cdnizerOptions: {
    defaultCDNBase: 'https://cdn.example.com',
  },
}),

With Dynamic Upload Options

new S3Plugin({
  s3Options: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
  s3UploadOptions: {
    Bucket: 'my-bucket-name',
    ContentEncoding(fileName) {
      if (/\.gz$/.test(fileName)) {
        return 'gzip';
      }
    },
    ContentType(fileName) {
      if (/\.js$/.test(fileName)) {
        return 'application/javascript';
      }
      return 'text/plain';
    },
  },
}),

With Priority Upload Order

new S3Plugin({
  priority: [
    /.*\.html$/,  // Upload HTML files last
    /.*\.css$/,   // Upload CSS files second to last
  ],
  s3Options: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
  s3UploadOptions: {
    Bucket: 'my-bucket-name',
  },
}),

Using AWS Credentials File

You can use AWS credentials file instead of environment variables:

const { fromIni } = require('@aws-sdk/credential-providers');

new S3Plugin({
  s3Options: {
    credentials: fromIni({ profile: 'my-profile' }),
    region: 'us-west-1',
  },
  s3UploadOptions: {
    Bucket: 'my-bucket-name',
  },
}),

Options

Option	Type	Default	Description
s3Options	Object	{}	AWS S3 client configuration (required)
s3UploadOptions	Object	{}	S3 upload options. Must include Bucket (required)
include	RegExp/Function/Array/String	undefined	Pattern to match files to include
exclude	RegExp/Function/Array/String	undefined	Pattern to match files to exclude
basePath	String	''	Base path prefix for uploaded files
basePathTransform	Function	(path) => path	Transform function for base path (can return Promise)
directory	String	output.path	Directory to upload (if not set, uses compilation assets)
htmlFiles	String/Array	[]	HTML files to process with cdnizer
cdnizerOptions	Object	{}	Options for cdnizer (if empty, cdnizer is disabled)
cloudfrontInvalidateOptions	Object	{}	CloudFront invalidation options
progress	Boolean	true	Show upload progress
priority	Array	undefined	Priority order for file uploads

s3Options

AWS SDK v3 S3 client configuration. See AWS SDK v3 S3 Client documentation.

s3UploadOptions

S3 upload parameters. See AWS SDK v3 PutObjectCommand documentation.

Required:

• Bucket: The S3 bucket name

Optional:

• Key: Can be a function (fileName, filePath) => string
• ContentType: Can be a function (fileName, filePath) => string
• ContentEncoding: Can be a function (fileName, filePath) => string
• Any other S3 PutObject parameters

cloudfrontInvalidateOptions

• DistributionId: String or Array of CloudFront distribution IDs
• Items: Array of paths to invalidate (e.g., ['/*'])

Advanced Include/Exclude Rules

The include and exclude options support multiple rule types:

• RegExp: Regular expression to test against file path
• Function: Function that receives the file path and returns boolean
• Array: Array of rules (all must match for include, any match for exclude)
• String: String pattern converted to RegExp

Example:

new S3Plugin({
  include: [
    /.*\.(css|js)$/,
    (filePath) => filePath.includes('assets'),
  ],
  exclude: /.*\.map$/,
  // ... other options
}),

Differences from webpack-s3-plugin

• Uses Rspack's getAssets() API instead of compilation.assets
• Uses native fs.promises instead of recursive-readdir
• Replaced lodash with native JavaScript methods
• Replaced progress package with lightweight custom implementation
• Updated to latest AWS SDK v3
• Updated mime to v4
• Built specifically for Rspack (not compatible with Webpack)

Migration from webpack-s3-plugin

The API is identical to webpack-s3-plugin, so you can simply replace the import:

// Before
const S3Plugin = require("webpack-s3-plugin");

// After
const S3Plugin = require("rspack-s3-plugin");

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

This plugin is based on webpack-s3-plugin by Mika Kalathil, adapted for Rspack.