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

    grunt-zippublic

    grunt-zip Build status

    Zip and unzip files via a grunt plugin

    This was created for dependency management via grunt-curl and grunt-zip as a low-tech alternative to bower and similar solutions.

    http://twolfson.com/2014-01-19-low-tech-dependency-management-via-grunt-tasks

    Features

    • Zip and unzip support
    • Per-file renaming/routing via router option
    • File skipping via router option
    • Preservation of UNIX file permissions during extraction

    Getting Started

    grunt-zip can be installed via npm: npm install grunt-zip

    grunt-zip provides 2 grunt tasks: zip and unzip

    zip

    Compress files into a zip file

    // Inside your Gruntfile.js
    module.exports = function (grunt) {
      // Define a zip task
      grunt.initConfig({
        zip: {
          'location/to/zip/files.zip': ['file/to/zip.js', 'another/file.css']
        }
      });
     
      // Load in `grunt-zip`
      grunt.loadNpmTasks('grunt-zip');
    };

    Now, we can run our task:

    $ grunt zip
    Running "zip:location/to/zip/files.zip" (zip) task
    File "location/to/zip/files.zip" created.
     
    Done, without errors.

    unzip

    Extract files from a zip file

    // Inside your Gruntfile.js
    module.exports = function (grunt) {
      // Define an unzip task
      grunt.initConfig({
        unzip: {
          'location/to/extract/files/': 'file/to/extract.zip'
        }
      });
     
      // Load in `grunt-zip`
      grunt.loadNpmTasks('grunt-zip');
    };

    Now, we can run our task:

    $ grunt unzip
    Running "unzip:location/to/extract/files/" (unzip) task
    Created "location/to/extract/files/" directory
     
    Done, without errors.

    Documentation

    zip

    Short format

    The short format relies on grunt's support of {dest: src}

    zip: {
      'location/to/zip/files.zip': ['file/to/zip.js', 'another/file.css']
    }

    This format is suggested only if you don't need to run zip tasks separately

    grunt zip

    If you want to run this task standalone, it must be executed via:

    grunt zip:dest
    # grunt zip:location/to/zip/files.zip 

    Long format

    zip: {
      'long-format': {
        src: ['file/to/zip.js', 'another/file.css'],
        dest: 'location/to/zip/files.zip'
      }
    }

    Using cwd

    The cwd option sets the base path for the zipped files

    zip: {
      'using-cwd': {
        cwd: 'nested/'
        // Files will zip to 'hello.js' and 'world.js'
        src: ['nested/hello.js', 'nested/world.js'],
        dest: 'location/to/zip/files.zip'
      }
    }

    Using router

    The router option allows for adjust file paths on a per-file basis. This cannot be used with cwd since there are ordering conflicts.

    // This example requires using node's `path` module
    var path = require('path');
     
    // Inside grunt config
    zip: {
      'using-router': {
        // `router` receives the path from grunt (e.g. js/main.js)
        // The path it returns is what the file contents are saved as (e.g. all/main.js)
        router: function (filepath) {
          // Route each file to all/{{filename}}
          var filename = path.basename(filepath);
          return 'all/' + filename;
        },
     
        // Files will zip to 'main.js' and 'main.css'
        src: ['js/main.js', 'css/main.css'],
        dest: 'files.zip'
      }
    }

    Remaining options

    We allow for specifying the DEFLATE comrpession algorithm, base64 encoding, and including dotfiles (e.g. .travis.yml) via the following options:

    zip: {
      'using-delate': {
        src: ['file.js'],
        dest: 'files.zip',
        compression: 'DEFLATE'
      },
      'encode-base64': {
        src: ['file.js'],
        dest: 'files.zip',
        base64: true
      },
      'including-dotfiles': {
        src: ['file.js'],
        dest: 'files.zip',
        dot: true
      }
    }

    unzip

    Short format

    As with zip, we support the {dest: src} format. Additionally, it has the same drawbacks of being difficult to run standalone.

    unzip: {
      'location/to/extract/files': 'file/to/extract.zip'
    }

    Long format

    unzip: {
      'long-format': {
        // Note: If you provide multiple src files, they will all be extracted to the same folder.
        // This is not well-tested behavior so use at your own risk.
        src: 'file/to/extract.zip',
        dest: 'location/to/extract/files'
      }
    }

    Using router

    During extraction, we can dynamically change the filepaths of the zip's contents via the router option.

    // This example requires using node's `path` module
    var path = require('path');
     
    // Inside grunt config
    unzip: {
      'using-router': {
        // `router` receives the path that was used during zipping (e.g. css/bootstrap.css)
        // The path it returns is where the file contents will be written to (e.g. dist/bootstrap.css)
        router: function (filepath) {
          // Route each file to dist/{{filename}}
          var filename = path.basename(filepath);
          return 'dist/' + filename;
        },
     
        // Collects all nested files in same directory
        // css/bootstrap.css -> bootstrap.css, js/bootstrap.js -> bootstrap.js
        src: 'bootstrap.zip',
        dest: 'bootstrap/'
      }
    }

    Remaining options

    With the following options we can disable the CRC32 check or decode from base64 encoding:

    zip: {
      'skip-crc32-check': {
        src: 'bootstrap.zip',
        dest: 'bootstrap/',
        checkCRC32: false
      },
      'decode-base64': {
        src: ['file.js'],
        dest: 'files.zip',
        base64: true
      }
    }

    Examples

    Skipping files during zip

    zip's router allows for returning null to skip over a file.

    zip: {
      'skip-files': {
        // Skip over non-js files
        router: function (filepath) {
          // Grab the extension
          var extname = path.extname(filepath);
     
          // If the file is a .js, add it to the zip
          if (extname === '.js') {
            return filepath;
          } else {
          // Otherwise, skip it
            return null;
          }
        },
     
        src: ['js/main.js', 'css/main.css'],
        dest: 'js-only.zip'
      }
    }

    Skipping files during unzip

    As with zip, unzip supports skipping extracting of files by returning null in router.

    unzip: {
      'skip-files': {
        // Skip over non-css files
        router: function (filepath) {
          // Grab the extension
          var extname = path.extname(filepath);
     
          // If the file is a .css, extract it
          if (extname === '.css') {
            return filepath;
          } else {
          // Otherwise, skip it
            return null;
          }
        },
     
        src: ['bootstrap.css'],
        dest: 'bootstrap-css/'
      }
    }

    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 your code using grunt and test via npm test.

    Donating

    Support this project and others by twolfson via gittip.

    Support via Gittip

    License

    Copyright (c) 2013 Todd Wolfson Licensed under the MIT license.

    install

    npm i grunt-zip

    Downloadsweekly downloads

    10,165

    version

    0.17.1

    license

    none

    repository

    githubgithub

    last publish

    collaborators

    • avatar