/docbits/30_export.md | sheetjs@v0.18.3

Packaging and Releasing Data

Writing Workbooks

API

Generate spreadsheet bytes (file) from data

var data = XLSX.write(workbook, opts);

The write method attempts to package data from the workbook into a file in memory. By default, XLSX files are generated, but that can be controlled with the bookType property of the opts argument. Based on the type option, the data can be stored as a “binary string”, JS string, Uint8Array or Buffer.

The second opts argument is required. “Writing Options” covers the supported properties and behaviors.

Generate and attempt to save file

XLSX.writeFile(workbook, filename, opts);

The writeFile method packages the data and attempts to save the new file. The export file format is determined by the extension of filename (SheetJS.xlsx signals XLSX export, SheetJS.xlsb signals XLSB export, etc).

The writeFile method uses platform-specific APIs to initiate the file save. In NodeJS, fs.readFileSync can create a file. In the web browser, a download is attempted using the HTML5 download attribute, with fallbacks for IE.

Generate and attempt to save an XLSX file

XLSX.writeFileXLSX(workbook, filename, opts);

The writeFile method embeds a number of different export functions. This is great for developer experience but not amenable to tree shaking using the current developer tools. When only XLSX exports are needed, this method avoids referencing the other export functions.

The second opts argument is optional. “Writing Options” covers the supported properties and behaviors.

Examples

Local file in a NodeJS server (click to show)

writeFile uses fs.writeFileSync in server environments:

var XLSX = require("xlsx");

/* output format determined by filename */
XLSX.writeFile(workbook, "out.xlsb");

For Node ESM, the writeFile helper is not enabled. Instead, fs.writeFileSync should be used to write the file data to a Buffer for use with XLSX.write:

import { writeFileSync } from "fs";
import { write } from "xlsx/xlsx.mjs";

const buf = write(workbook, {type: "buffer", bookType: "xlsb"});
/* buf is a Buffer */
const workbook = writeFileSync("out.xlsb", buf);

Local file in a Deno application (click to show)

writeFile uses Deno.writeFileSync under the hood:

// @deno-types="https://deno.land/x/sheetjs/types/index.d.ts"
import * as XLSX from 'https://deno.land/x/sheetjs/xlsx.mjs'

XLSX.writeFile(workbook, "test.xlsx");

Applications writing files must be invoked with the --allow-write flag. The deno demo has more examples

Local file in a PhotoShop or InDesign plugin (click to show)

writeFile wraps the File logic in Photoshop and other ExtendScript targets. The specified path should be an absolute path:

#include "xlsx.extendscript.js"

/* output format determined by filename */
XLSX.writeFile(workbook, "out.xlsx");
/* at this point, out.xlsx is a file that you can distribute */

The extendscript demo includes a more complex example.

Download a file in the browser to the user machine (click to show)

XLSX.writeFile wraps a few techniques for triggering a file save:

URL browser API creates an object URL for the file, which the library uses by creating a link and forcing a click. It is supported in modern browsers.
msSaveBlob is an IE10+ API for triggering a file save.
IE_FileSave uses VBScript and ActiveX to write a file in IE6+ for Windows XP and Windows 7. The shim must be included in the containing HTML page.

There is no standard way to determine if the actual file has been downloaded.

/* output format determined by filename */
XLSX.writeFile(workbook, "out.xlsb");
/* at this point, out.xlsb will have been downloaded */

Download a file in legacy browsers (click to show)

XLSX.writeFile techniques work for most modern browsers as well as older IE. For much older browsers, there are workarounds implemented by wrapper libraries.

FileSaver.js implements saveAs. Note: XLSX.writeFile will automatically call saveAs if available.

/* bookType can be any supported output type */
var wopts = { bookType:"xlsx", bookSST:false, type:"array" };

var wbout = XLSX.write(workbook,wopts);

/* the saveAs call downloads a file on the local machine */
saveAs(new Blob([wbout],{type:"application/octet-stream"}), "test.xlsx");

Downloadify uses a Flash SWF button to generate local files, suitable for environments where ActiveX is unavailable:

Downloadify.create(id,{
  /* other options are required! read the downloadify docs for more info */
  filename: "test.xlsx",
  data: function() { return XLSX.write(wb, {bookType:"xlsx", type:"base64"}); },
  append: false,
  dataType: "base64"
});

The oldie demo shows an IE-compatible fallback scenario.

Browser upload file (ajax) (click to show)

A complete example using XHR is included in the XHR demo, along with examples for fetch and wrapper libraries. This example assumes the server can handle Base64-encoded files (see the demo for a basic nodejs server):

/* in this example, send a base64 string to the server */
var wopts = { bookType:"xlsx", bookSST:false, type:"base64" };

var wbout = XLSX.write(workbook,wopts);

var req = new XMLHttpRequest();
req.open("POST", "/upload", true);
var formdata = new FormData();
formdata.append("file", "test.xlsx"); // <-- server expects `file` to hold name
formdata.append("data", wbout); // <-- `data` holds the base64-encoded data
req.send(formdata);

PhantomJS (Headless Webkit) File Generation (click to show)

The headless demo includes a complete demo to convert HTML files to XLSB workbooks using PhantomJS. PhantomJS fs.write supports writing files from the main process but has a different interface from the NodeJS fs module:

var XLSX = require('xlsx');
var fs = require('fs');

/* generate a binary string */
var bin = XLSX.write(workbook, { type:"binary", bookType: "xlsx" });
/* write to file */
fs.write("test.xlsx", bin, "wb");

Note: The section “Processing HTML Tables” shows how to generate a workbook from HTML tables in a page in “Headless WebKit”.

The included demos cover mobile apps and other special deployments.

Writing Examples

http://sheetjs.com/demos/table.html exporting an HTML table
http://sheetjs.com/demos/writexlsx.html generates a simple file

Streaming Write

The streaming write functions are available in the XLSX.stream object. They take the same arguments as the normal write functions but return a Readable Stream. They are only exposed in NodeJS.

XLSX.stream.to_csv is the streaming version of XLSX.utils.sheet_to_csv.
XLSX.stream.to_html is the streaming version of XLSX.utils.sheet_to_html.
XLSX.stream.to_json is the streaming version of XLSX.utils.sheet_to_json.

nodejs convert to CSV and write file (click to show)

var output_file_name = "out.csv";
var stream = XLSX.stream.to_csv(worksheet);
stream.pipe(fs.createWriteStream(output_file_name));

nodejs write JSON stream to screen (click to show)

/* to_json returns an object-mode stream */
var stream = XLSX.stream.to_json(worksheet, {raw:true});

/* the following stream converts JS objects to text via JSON.stringify */
var conv = new Transform({writableObjectMode:true});
conv._transform = function(obj, e, cb){ cb(null, JSON.stringify(obj) + "\n"); };

stream.pipe(conv); conv.pipe(process.stdout);

https://github.com/sheetjs/sheetaki pipes write streams to nodejs response.