@steveush/grunt-jszip

grunt-jszip v0.0.1

Grunts tasks for working with ZIP files.

Some basic tasks that wrap the JSZip library to provide the ability to both zip and unzip files and folders.

Getting Started

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 @steveush/grunt-jszip --save-dev

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

grunt.loadNpmTasks('@steveush/grunt-jszip');

This plugin was designed to work with Grunt 0.4.x. If you're still using grunt v0.3.x it's strongly recommended that you upgrade

JSZip Task

Run this task with the grunt jszip command.

Task targets, files and options may be specified according to the grunt Configuring tasks guide.

Options

compression

Type: String
Default: "DEFLATE"

Set the compression method used by JSZip. Can be either "DEFLATE" or "STORE". See the JSZip documentation for more information.

compressionLevel

Type: Number
Default: 9

Set the compression level to between 1 (best speed) and 9 (best compression). This is a shortcut for the JSZip compressionOptions:{ level: number } option. See the JSZip documentation for more information.

router

Type: Function(String, String, Boolean):String|NULL
Default: ( relative, root, isFile ) => relative

A function that converts the relative file system path to a relative zip path. If null is returned the given path is not extracted.

Example Usage

Given the file and folder structure below:

target/
    .dot-dir/
        .dot-file
    sub-dir/
        another-file.txt
    some-file.txt
Gruntfile.js
package.json

Zip all files and folders in the target directory.

"jszip": {
    "output.zip": [ "target/**/*" ]
}

The output.zip would contain:

target/
    sub-dir/
        another-file.txt
    some-file.txt

You may notice that the folder .dot-dir and its child file .dot-file are missing from the output. To include files and folders starting with a period, you must set the Grunt dot option.

Zip all files and folders in the target directory including those starting with a period.

"jszip": {
    generate: {
        dot: true,
        src: [ "target/**/*" ],
        dest: 'output.zip'
    }
}

The output.zip would contain:

target/
    .dot-dir/
        .dot-file
    sub-dir/
        another-file.txt
    some-file.txt

Zip all files and folders in the target directory but do not include the target directory itself.

"jszip": {
    generate: {
        cwd: "target", //; change the working directory for the src files
        src: [ "**/*" ],
        dest: "output.zip" // the dest path does not use the changed cwd
    }
}

The output.zip would contain:

sub-dir/
    another-file.txt
some-file.txt

Zip all files and folders in the target directory but route some paths to a different location within the ZIP.

"jszip": {
    generate: {
        cwd: "target", //; change the working directory for the src files
        src: [ "**/*" ],
        dest: 'output.zip',
        options: {
            router: ( relative, root, isFile ) => {
                // rename a file within the zip.
                if ( relative === 'some-file.txt' )
                    return 'changed.txt';

                // exclude a file entirely from the zip.
                if ( relative === '.dot-dir/.dot-file' )
                    return null;

                // move a file within the zip.
                if ( relative === 'sub-dir/another-file.txt' )
                    return 'moved/another-file.txt';

                // no changes
                return relative;
            }
        }
    }
}

The output.zip would contain:

.dot-dir/
sub-dir/
moved/
    another-file.txt
changed.txt

If you also want to remove the now empty .dot-dir and sub-dir folders you would need to add in additional checks to the router function above.

router: ( relative, root, isFile ) => {
    // rename a file within the zip.
    if ( relative === 'some-file.txt' )
        return 'changed.txt';

    // exclude a set of paths entirely from the zip.
    if ( [ 'sub-dir', '.dot-dir', '.dot-dir/.dot-file' ].includes( relative ) )
        return null;

    // move a file within the zip.
    if ( relative === 'sub-dir/another-file.txt' )
        return 'moved/another-file.txt';

    // no changes
    return relative;
}

The output.zip would then contain:

moved/
    another-file.txt
changed.txt

JSUnzip Task

Options

checkCRC32

Type: Boolean
Default: true

The checkCRC32 option will load every file, compute the CRC32 value and compare it against the saved value. With larger zip files, this option can have a significant performance cost.

router

Type: Function(String, String, Boolean):String|NULL
Default: ( relative, root, isFile ) => relative

A function that converts the relative zip path to a relative file system path. If null is returned the given path is not extracted.