gulp plugin to publish files to amazon s3

npm install gulp-awspublish
7 downloads in the last day
74 downloads in the last week
299 downloads in the last month


NPM version Dependency Status

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
  var publisher = awspublish.create({ key: '...',  secret: '...', bucket: '...' });

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

  return gulp.src('./public/*.js')

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

    // publisher will add Content-Length, Content-Type and Cache-Control headers  
    // and if not specified will set x-amz-acl to public-read by default

    // create a cache file to speed up consecutive uploads

     // print upload updates to console 


add an aws-credentials.json json file to the project directory with your bucket credentials, then run mocha.

  "key": "...",
  "secret": "...",
  "bucket": "..."



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

Available options:

  • ext: file extension to add to gzipped file (eg: { ext: '.gz' })


Create a Publisher. Options are passed to knox to create a s3 client.


Create a through stream, that push files to s3.Publish take a header object that add or override existing s3 headers.

Files that go through the stream receive extra properties:

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


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 :).


create a transform stream that delete old files from the bucket. Both new and delete files are written to the stream. Deleted file will have s3.state property set to delete.

warning sync will delete files in your bucket that are not in your local folder.

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


The knox client object exposed to let you do other s3 operations.


Create a reporter that logs s3.path and s3.state (delete, create, update, 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

    .pipe(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


MIT License

npm loves you