grunt-s3-sync
v0.4.3
Published
A streaming interface for uploading multiple files to S3
Downloads
38
Readme
grunt-s3-sync
A streaming interface for uploading multiple files to S3
Getting Started
This plugin requires Grunt ~0.4.1
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-s3-sync --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-s3-sync');
The "s3-sync" task
Overview
In your project's Gruntfile, add a section named s3-sync
to the data object passed into grunt.initConfig()
.
Options
options.key
Type: String
Your AWS access key, mandatory.
options.secret
Type: String
Your AWS secret, mandatory.
options.bucket
Type: String
The bucket to upload to, mandatory.
options.concurrency
Type: Number
The maximum amount of files to upload concurrently.
options.retries
Type: Number
The maximum number of times to retry uploading a file before failing. By default the value is 7.
options.headers
Type: Object
Additional headers to include on each file.
options.db
Type: Function
A level database to use as a local cache for file uploads. This way, you can minimize the frequency you have to hit S3 and speed up the whole process considerably.
Needs to be passed as a function that returns the db instance - otherwise it'll get mangled by grunt's option API.
files.gzip
Type: Boolean
Pass this to a files object to enable gzip compression, e.g.
{
root: __dirname
src: '/**/*.html',
dest: '/',
gzip: true
}
files.compressionLevel
Type: Number
This argument will set compression to the desired level. The default is 6 and the maximum you can set is 9. This is only useful if gzip: true
. You can find more about this here.
files.root
Type: String
This is a mandatory argument. Pass this to a files object to determine the "root" directory for uploads, e.g.
the following will upload the files in build
to the bucket's root:
The purpose is to determine the base path of the files so that relative paths from that base path root
can be preserved when uploaded to S3. Without it, we don't know relative to what to make the paths on S3.
{
root: __dirname + 'build'
src: 'build/**'
dest: '/'
}
Note
The project is based on knox, all knox options are available in the
options
object.
Usage Examples
Template strings in grunt will allow you to easily include values from other files. The below example demonstrates loading aws settings from another file, Where grunt-aws.json is just a json key:value file like package.json. (Special thanks to @nanek) This is important because you should never check in your S3 credentials to github! Load them from an external file that is outside of the repo.
grunt.initConfig({
aws: grunt.file.readJSON('~/grunt-aws.json'),
's3-sync': {
options: {
key: '<%= aws.key %>'
, secret: '<%= aws.secret %>'
, bucket: '<%= aws.bucket %>'
, db : db
},
your_target: {
files: [
{
root: __dirname
, src: 'tasks/**/*.js'
, dest: 'js/'
, gzip: true
},
{
root: 'dist'
, src: ['dist/**', '!dist/img/**'] // Don't compress images!
, dest: '/<%= pkg.version %>/'
, gzip: true
, compressionLevel: 9 // Max compression
},
{
root: __dirname
, src: 'Gruntfile.js'
, dest: 'Gruntfile.js'
}
]
},
},
})
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style.
Release History
- 2013-08-07 v0.2.1 New s3-sync version
- 2013-07-25 v0.1.1 Edit gzipping handling
- 2013-07-25 v0.1.0 First release