grunt-http-upload

Grunt plugin to upload files through POST/PUT HTTP request

npm install grunt-http-upload
2 downloads in the last day
15 downloads in the last week
102 downloads in the last month

grunt-http-upload NPM version

Upload files through POST/PUT HTTP request, using Restler, the only Node library known to work flawlessly with multipart file uploads. So now you can push a zip /dist through your CMS' API!

Need Help?

If you wonder how to install or use this plugin, or even Grunt itself, you should check out our "Discover Grunt" book.

It starts at the very beginning (including how to properly set-up your command-line on Windows and Mac OS X), and goes beyond the official Getting Started guide.

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-http-upload --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-http-upload');

The "http_upload" task

Overview

In your project's Gruntfile, add a section named http_upload to the data object passed into grunt.initConfig().

grunt.initConfig({

  http_upload: {
    your_target: {
      options: {
        url: 'http://example.com/template/123/?token=<%= config.apiKey %>',
        method: 'PUT',
        data: {
          someKey: 'some value'
        }
      },
      src: '<%= yeoman.dist %>/dist.zip',
      dest: 'myField'
    },
  },

})

Options

options.url

Type: String Default value: ''

This is the full URL to which you can upload a file. You can append some variables, like an API token.

options.method

Type: String Default value: 'POST'

The HTTP method to use to upload the file. Look in the API documentation you want to use, this is usually POST or PUT.

options.data

Type: Object DefaultValue: {}

Any form data fields to be sent in addition to the file upload

src

Type: String Default value: ''

The local path of the file you wish to upload, using the current working directory as a reference. You can upload only 1 file at a time.

dest

Type: String Default value: ''

The field name of the file to be uploaded, on the API side.

Usage Examples

Default Options

In this example, the default POST method is used to upload the local picture ./images/status.jpg to Basecamp. Their API can be accessed through the URL https://basecamp.com (using Basic Auth). When creating an attachment in Basecamp, the "dest" field name is not important, so you can set it to anything (img in this case). method is set to "POST", but could have been omitted as this is the default value.

grunt.initConfig({
  http_upload: {
    basecamp: {
      options: {
        url: 'https://user:pwd@basecamp.com/99999999/api/v1/attachments.json',
        method: 'POST'
      },
      src: 'images/status.jpg',
      dest: 'img'
    }
  }
})

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

You should fork this repo, and issue a Pull Request with your proposed changes.

Roadmap ideas

For now the upload is limited to 1 file per target. This could change if I find a scenario needing it. Also, it is not possible to add additional payload (no custom data). A lot of API require the Authentication to be sent through the Headers, so this might be one of the next improvement.

Release History

  • 0.1.2 - 2014-04-03: Updated Restler to latest (3.2.0) version.
  • 0.1.1 - 2014-04-03: Added a data option to pass other form data in addition to the uploaded file (PR from mcondon).
  • 0.1.0 - 2013-10-30: Initial release. Supports only 1 multipart file upload.
npm loves you