Grunt HTTP Upload

0.3.2 · maintenance · verified Wed Apr 22

grunt-http-upload is a Grunt plugin designed for automating file uploads via POST or PUT HTTP requests directly within a Grunt build process. It allows developers to integrate file delivery to RESTful APIs or content management systems as part of their CI/CD or deployment workflows. The plugin currently sits at version 0.3.2, with its last update in 2016 primarily focused on replacing the deprecated `Restler` library with `Request` to ensure compatibility with newer Node.js versions (>=6.0.0). While Grunt itself has a less active development cadence compared to newer build tools, this plugin remains functional for existing Grunt-based projects needing straightforward HTTP file uploads. Its key differentiator is its deep integration into the Grunt ecosystem, simplifying what would otherwise require custom scripting or external `curl` commands.

Common errors

```
Warning: Task "http_upload" not found. Use --force to continue.
```
cause The Grunt plugin `grunt-http-upload` was installed but not loaded in the Gruntfile.

fix Add `grunt.loadNpmTasks('grunt-http-upload');` to your `Gruntfile.js` after defining `grunt.initConfig()`.
```
Error: Cannot find module 'restler'
```
cause An older version of `grunt-http-upload` (<0.3.2) is being used with a Node.js version (typically >=6.0.0) where the `restler` dependency is no longer compatible or installed.

fix Update `grunt-http-upload` to version `0.3.2` or higher using `npm install grunt-http-upload@latest --save-dev` to switch to the `request` library.
```
Error: Peer dependency "grunt@>=0.4.0" not installed.
```
cause The `grunt` package, which is a peer dependency, is not installed in the project's `node_modules`.

fix Install `grunt` locally: `npm install grunt --save-dev`.

Warnings

breaking Version 0.3.2 replaced the `Restler` HTTP client with `Request`. While this fixed deprecation warnings on Node.js >= 6.0.0, it constitutes a significant internal dependency change. Users upgrading from earlier versions might experience subtle behavioral differences if relying on specific `Restler` quirks.
Fix: Ensure your Grunt environment is running on Node.js versions compatible with the `Request` library. Test upload configurations thoroughly after upgrading to v0.3.2 or later.
gotcha The `rejectUnauthorized` option, when set to `false`, disables SSL certificate verification. This should only be used in development or controlled environments as it exposes the connection to man-in-the-middle attacks.
Fix: Always aim to use `rejectUnauthorized: true` (the default) and ensure your server's SSL certificate chain is correctly configured and trusted by Node.js. Update server certificates if necessary.
gotcha The plugin is designed to upload only a single file per task target. The `src` option expects a single file path string, not an array or a glob pattern for multiple files.
Fix: If multiple files need to be uploaded, configure separate `http_upload` task targets for each file or consider using a different plugin designed for multi-file operations.
deprecated The underlying `request` library, which `grunt-http-upload` depends on, has been deprecated since 2018 and is no longer actively maintained. While it may still function, it will not receive security patches or feature updates, posing a long-term risk.
Fix: Consider migrating to a more modern build tool or finding an alternative Grunt plugin that uses a currently maintained HTTP client if active maintenance and security updates are critical for your project.

Install

npm install grunt-http-upload npm
yarn add grunt-http-upload yarn
pnpm add grunt-http-upload pnpm

Imports

grunt.loadNpmTasks
wrong:
```
import { http_upload } from 'grunt-http-upload';
```
correct:
```
grunt.loadNpmTasks('grunt-http-upload');
```
Grunt plugins are loaded as tasks using `loadNpmTasks` within a `Gruntfile.js` or `Gruntfile.coffee`. They do not expose direct symbols for `import` or `require` in application code.
http_upload task configuration
```
grunt.initConfig({
  http_upload: { /* ... task configuration ... */ }
});
```
The `http_upload` task is configured within the `grunt.initConfig()` object, defining targets and options for file uploads. This is the primary way to interact with the plugin's functionality.

Quickstart

Demonstrates how to configure and run the `http_upload` Grunt task to upload a file to a specified API endpoint, including options for URL, method, headers, and data fields.

module.exports = function(grunt) {
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    http_upload: {
      your_target: {
        options: {
          url: 'https://api.example.com/upload?token=<%= pkg.apiKey %>', // Use template for API key or env var
          method: 'POST',
          rejectUnauthorized: true, // Typically set to true for production
          headers: {
            'Authorization': 'Bearer <%= process.env.UPLOAD_TOKEN ?? "" %>'
          },
          data: {
            version: '<%= pkg.version %>',
            environment: 'production'
          },
          onComplete: function(response) {
            console.log('Upload complete. Server response:', response);
          }
        },
        src: 'dist/<%= pkg.name %>-<%= pkg.version %>.zip', // Source file to upload
        dest: 'file' // Field name for the uploaded file on the API side
      },
    },
  });

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

  // A default task to run the upload
  grunt.registerTask('deploy', ['http_upload:your_target']);

  // Example of a minimal package.json excerpt for the quickstart to be runnable:
  // { "name": "my-project", "version": "1.0.0", "apiKey": "YOUR_API_KEY" }
  // Remember to set UPLOAD_TOKEN environment variable or replace with actual token.
};

view raw JSON →