file(name, data [,options])

Add (or update) a file to the zip file. If something goes wrong (the data is not in a supported format for example), an exception will be propagated when accessing the data.

Returns : The current JSZip object, for chaining.

Since: v1.0.0

Arguments

name type description
name string the name of the file. You can specify folders in the name : the folder separator is a forward slash (“/”).
data String/ArrayBuffer/Uint8Array/Buffer/Blob/Promise/Nodejs stream the content of the file.
options object the options.

Content of options :

name type default description
base64 boolean false set to true if the data is base64 encoded. For example image data from a <canvas> element. Plain text and HTML do not need this option. More.
binary boolean false set to true if the data should be treated as raw content, false if this is a text. If base64 is used, this defaults to true, if the data is not a string, this will be set to true. More.
date date the current date the last modification date. More.
compression string null If set, specifies compression method to use for this specific file. If not, the default file compression will be used, see generateAsync(options). More.
compressionOptions object null the options to use when compressing the file, see generateAsync(options). More.
comment string null The comment for this file. More.
optimizedBinaryString boolean false Set to true if (and only if) the input is a “binary string” and has already been prepared with a 0xFF mask.
createFolders boolean true Set to true if folders in the file path should be automatically created, otherwise there will only be virtual folders that represent the path to the file. More.
unixPermissions 16 bits number null The UNIX permissions of the file, if any. More.
dosPermissions 6 bits number null The DOS permissions of the file, if any. More.
dir boolean false Set to true if this is a directory and content should be ignored. More.

data input

You shouldn’t update the data given to this method: it is kept as it so any update will impact the stored data.

About Promise since v3.0.0

You can use a Promise of content directly to simplify async content handling. Let’s use HTTP calls as examples:

/** with promises **/

// instead of
$.get("url/to.file.txt") // jQuery v3 returns promises
.then(function (content) {
    zip.file("file.txt", content);
})

// you can do
var promise = $.get("url/to.file.txt");
zip.file("file.txt", promise);

/** with callbacks **/

// instead of
request('url/to.file.txt', function (error, response, body) {
    zip.file("file.txt", body);
});

// you can do
var promise = new Promise(function (resolve, reject) {
    request('url/to.file.txt', function (error, response, body) {
        if (error) {
            reject(error);
        } else {
          resolve(body);
        }
    });
});
zip.file("file.txt", promise);

About Blob since v3.0.0

You can use directly Blob as input, no need to use a FileReader. File objects are Blobs so you can use them directly:

// in a change callback of a <input type="file">
var files = evt.target.files;
for (var i = 0; i < files.length; i++) {
    var f = files[i];
    zip.file(f.name, f);
}

About nodejs stream since v3.0.0

A stream can’t be restarted: if it is used once, it can’t be used again ( by generateAsync() or by ZipObject methods). In that case, the promise/stream (depending on the method called) will get an error.

base64 option

var zip = new JSZip();
zip.file("hello.txt", "aGVsbG8gd29ybGQK", {base64: true});

binary option

var zip = new JSZip();

// here, we have a correct (unicode) string
zip.file("hello.txt", "unicode ♥", {binary: false});

// here, we have a binary string: it can contain binary content, one byte
// per character.
zip.file("hello.txt", "unicode \xE2\x99\xA5", {binary: true});

If you use a library that returns a binary string for example, you should use this option. Otherwise, you will get a corrupted result: JSZip will try to encode this string with UTF-8 when the content doesn’t need to.

date option

zip.file("Xmas.txt", "Ho ho ho !", {
    date: new Date("December 25, 2007 00:00:01")
});

compression and compressionOptions options

See also the same options on JSZip#generateAsync().

These options will be used when generating a zip file. They let you override entry per entry the compression / compression options to use.

zip.file("a.png", contentOfA, {
    compression: "STORE" // force a compression for this file
});
zip.file("b.txt", contentOfA, {
    compression: "DEFLATE",
    compressionOptions: {
        level: 9 // force a compression and a compression level for this file
    }
});

// don't force anything, use the generateAsync options
zip.file("c.txt", contentOfB);

// here:
// - a.png will not be compressed (STORE)
// - b.txt will be compressed at maximum level
// - c.txt will be compressed with the default compression level
zip.generateAsync({
    type: "blob",
    compression: "DEFLATE"
});

comment option

zip.file("a.txt", "content", {
    comment: "comment of a.txt"
});

createFolders option

zip.file("a/b/c/d.txt", "content", {
    createFolders: true // default value
});
console.log(zip.files);
// will display:
// - a/
// - a/b/
// - a/b/c/
// - a/b/c/d.txt


zip.file("a/b/c/d.txt", "content", {
    createFolders: false
});
console.log(zip.files);
// will display:
// - a/b/c/d.txt

unixPermissions and dosPermissions options

Each permission will be used for matching platform option of generateAsync(): on DOS, use dosPermissions, on UNIX, use unixPermissions.

On nodejs you can use the mode attribute of nodejs’ fs.Stats.

When not set, a default value will be generated:

  • 0100664 or 040775 for UNIX
  • standard file or standard directory for DOS

The field unixPermissions also accepts a string representing the octal value: “644”, “755”, etc.

zip.file("script.sh", "#!/bin/bash", {
    unixPermissions: "755"
});

dir option

If dir is true or if a permission says it’s a folder, this entry be flagged as a folder and the content will be ignored.

See also folder(name).

zip.file("folder/", null, {
    dir: true
});

Other examples

zip.file("Hello.txt", "Hello World\n");

// base64
zip.file("smile.gif", "R0lGODdhBQAFAIACAAAAAP/eACwAAAAABQAFAAACCIwPkWerClIBADs=", {base64: true});
// from an ajax call with xhr.responseType = 'arraybuffer'
zip.file("smile.gif", arraybufferFromXhr);
// or on nodejs
zip.file("smile.gif", fs.readFileSync("smile.gif"));

zip.file("Xmas.txt", "Ho ho ho !", {date : new Date("December 25, 2007 00:00:01")});
zip.file("folder/file.txt", "file in folder");

zip.file("animals.txt", "dog,platypus\n").file("people.txt", "james,sebastian\n");

// result:
// - Hello.txt
// - smile.gif
// - Xmas.txt
// - animals.txt
// - people.txt
// - folder/
// - folder/file.txt