Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    grunt-s3-syncpublic

    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

    install

    npm i grunt-s3-sync

    Downloadsweekly downloads

    107

    version

    0.4.3

    license

    none

    repository

    githubgithub

    last publish

    collaborators

    • avatar
    • avatar
    • avatar