Gulp Awspublish

gulp plugin to publish files to amazon s3
Alternatives To Gulp Awspublish
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Awesome Aws11,514
4 days ago1December 21, 201565otherPython
A curated list of awesome Amazon Web Services (AWS) libraries, open source repos, guides, blogs, and other resources. Featuring the Fiery Meter of AWSome.
S3fs Fuse7,180
a day ago4March 09, 2022215gpl-2.0C++
FUSE-based file system backed by Amazon S3
19 hours ago52apache-2.0Python
A library that allows you to easily mock out tests based on AWS infrastructure.
3 months ago82gpl-3.0Rust
Seed your development database with real data ⚡️
Wal E3,327
14a year ago33February 04, 202091bsd-3-clausePython
Continuous Archiving for Postgres
a year ago2mit
📫 A serverless email server on AWS using S3 and SES
Mountpoint S32,572
2 days ago27apache-2.0Rust
A simple, high-throughput file client for mounting an Amazon S3 bucket as a local file system.
Wal G2,561
19 hours ago62March 16, 2022238otherGo
Archival and Restoration for databases in the Cloud
Mc2,4631515a day ago50April 22, 202137agpl-3.0Go
Simple | Fast tool to manage MinIO clusters :cloud:
Aws Sdk Js V32,39142712 hours ago156September 27, 2022350apache-2.0TypeScript
Modularized AWS SDK for JavaScript.
Alternatives To Gulp Awspublish
Select To Compare

Alternative Project Comparisons


NPM version Build Status Dependency Status Install size

awspublish plugin for gulp


First, install gulp-awspublish as a development dependency:

npm install --save-dev gulp-awspublish

Then, add it to your gulpfile.js:

var awspublish = require("gulp-awspublish");

gulp.task("publish", function() {
  // create a new publisher using S3 options
  var publisher = awspublish.create(
      region: "your-region-id",
      params: {
        Bucket: "..."
      cacheFileName: "your-cache-location"

  // define custom headers
  var headers = {
    "Cache-Control": "max-age=315360000, no-transform, public"
    // ...

  return (
      // gzip, Set Content-Encoding headers and add .gz extension
      .pipe(awspublish.gzip({ ext: ".gz" }))

      // publisher will add Content-Length, Content-Type and headers specified above
      // If not specified it will set x-amz-acl to public-read by default

      // create a cache file to speed up consecutive uploads

      // print upload updates to console

// output
// [gulp] [create] file1.js.gz
// [gulp] [create] file2.js.gz
// [gulp] [update] file3.js.gz
// [gulp] [cache]  file3.js.gz
// ...
  • Note: If you follow the aws-sdk suggestions for providing your credentials you don't need to pass them in to create the publisher.

  • Note: In order for publish to work on S3, your policy has to allow the following S3 actions:

  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": ["arn:aws:s3:::BUCKETNAME"]
      "Effect": "Allow",
      "Action": [
      "Resource": ["arn:aws:s3:::BUCKETNAME/*"]

Bucket permissions

By default, the plugin works only when public access to the bucket is not blocked:

  • Block all public access: Off
    • Block public access to buckets and objects granted through new access control lists (ACLs): Off
    • Block public access to buckets and objects granted through any access control lists (ACLs): Off
    • Block public access to buckets and objects granted through new public bucket policies: Off
    • Block public and cross-account access to buckets and objects through any public bucket policies: Off

When dealing with a private bucket, make sure to pass the option { noAcl: true } or a value for the x-amz-acl header:

publisher.publish({}, { noAcl: true });
publisher.publish({ "x-amz-acl": "something" });


  1. Create an S3 bucket which will be used for the tests. Optionally create an IAM user for running the tests.
  2. Set the buckets Permission, so it can be edited by the IAM user who will run the tests.
  3. Add an aws-credentials.json file to the project directory with the name of your testing buckets and the credentials of the user who will run the tests.
  4. Run npm test
  "params": {
    "Bucket": "<test-bucket-name>"
  "credentials": {
    "accessKeyId": "<your-access-key-id>",
    "secretAccessKey": "<your-secret-access-key>",
    "signatureVersion": "v3"



create a through stream, that gzip file and add Content-Encoding header.

  • Note: Node version 0.12.x or later is required in order to use awspublish.gzip. If you need an older node engine to work with gzipping, you can use v2.0.2.

Available options:

  • ext: file extension to add to gzipped file (eg: { ext: '.gz' })
  • smaller: gzip files only when result is smaller
  • Any options that can be passed to zlib.gzip

awspublish.create(AWSConfig, cacheOptions)

Create a Publisher. The AWSConfig object is used to create an aws-sdk S3 client. At a minimum you must pass a Bucket key, to define the site bucket. You can find all available options in the AWS SDK documentation.

The cacheOptions object allows you to define the location of the cached hash digests. By default, they will be saved in your projects root folder in a hidden file called '.awspublish-' + 'name-of-your-bucket'.

Adjusting upload timeout

The AWS client has a default timeout which may be too low when pushing large files (> 50mb). To adjust timeout, add httpOptions: { timeout: 300000 } to the AWSConfig object.


By default, gulp-awspublish uses the credential chain specified in the AWS docs.

Here are some example credential configurations:

Hardcoded credentials (Note: We recommend you not hard-code credentials inside an application. Use this method only for small personal scripts or for testing purposes.):

var publisher = awspublish.create({
  region: "your-region-id",
  params: {
    Bucket: "..."
  credentials: {
    accessKeyId: "akid",
    secretAccessKey: "secret"

Using a profile by name from ~/.aws/credentials:

var AWS = require("aws-sdk");

var publisher = awspublish.create({
  region: "your-region-id",
  params: {
    Bucket: "..."
  credentials: new AWS.SharedIniFileCredentials({ profile: "myprofile" })

Instead of putting anything in the configuration object, you can also provide the following environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_PROFILE. You can also define a [default] profile in ~/.aws/credentials which the SDK will use transparently without needing to set anything.

Publisher.publish([headers], [options])

Create a through stream, that push files to s3.

  • header: hash of headers to add or override to existing s3 headers.
  • options: optional additional publishing options
    • force: bypass cache / skip
    • putOnly: bypass cache and head request (overrides force)
    • noAcl: do not set x-amz-acl by default
    • simulate: debugging option to simulate s3 upload
    • createOnly: skip file updates

Files that go through the stream receive extra properties:

  • s3.path: s3 path
  • s3.etag: file etag
  • file last modified date
  • s3.state: publication state (create, update, put, delete, cache or skip)
  • s3.headers: s3 headers for this file. Defaults headers are:
    • x-amz-acl: public-read
    • Content-Type
    • Content-Length

Note: publish will never delete files remotely. To clean up unused remote files use sync.


Create a through stream that create or update a cache file using file s3 path and file etag. Consecutive runs of publish will use this file to avoid reuploading identical files.

Cache file is save in the current working dir and is named .awspublish-<bucket>. The cache file is flushed to disk every 10 files just to be safe.

Publisher.sync([prefix], [whitelistedFiles])

create a transform stream that delete old files from the bucket.

  • prefix: prefix to sync a specific directory
  • whitelistedFiles: array that can contain regular expressions or strings that match against filenames that should never be deleted from the bucket.


// only directory bar will be synced
// files in folder /foo/bar and file baz.txt will not be removed from the bucket despite not being in your local folder
  .pipe(publisher.sync("bar", [/^foo\/bar/, "baz.txt"]))

warning sync will delete files in your bucket that are not in your local folder unless they're whitelisted.

// this will publish and sync bucket files with the one in your public directory

// output
// [gulp] [create] file1.js
// [gulp] [update] file2.js
// [gulp] [delete] file3.js
// ...


The aws-sdk S3 client is exposed to let you do other s3 operations.


Create a reporter that logs s3.path and s3.state (delete, create, update, put, cache, skip).

Available options:

  • states: list of state to log (default to all)
// this will publish,sync bucket files and print created, updated and deleted files
      states: ["create", "update", "delete"]


Rename file & directory

You can use gulp-rename to rename your files on s3

// see examples/rename.js

    rename(function(path) {
      path.dirname += "/s3-examples";
      path.basename += "-s3";

// output
// [gulp] [create] s3-examples/bar-s3.js
// [gulp] [create] s3-examples/foo-s3.js

Upload file in parallel

You can use concurrent-transform to upload files in parallel to your amazon bucket

var parallelize = require("concurrent-transform");

  .pipe(parallelize(publisher.publish(), 10))

Upload both gzipped and plain files in one stream

You can use the merge-stream plugin to upload two streams in parallel, allowing sync to work with mixed file types

var merge = require("merge-stream");
var gzip = gulp.src("public/**/*.js").pipe(awspublish.gzip());
var plain = gulp.src(["public/**/*", "!public/**/*.js"]);

merge(gzip, plain)



A router for defining file-specific rules


Invalidate cloudfront cache based on output from awspublish


MIT License

Popular S3 Projects
Popular Amazon Web Services Projects
Popular Cloud Computing Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.