ExcelWorkbook

An Excel workbook to read, write, style and save.

const wb = workbook.excelWorkbook(false);

wb.writeString(0, 0, "Region");
wb.writeString(0, 1, "Revenue");
wb.writeString(1, 0, "North");
wb.writeNumber(1, 1, 5000, "#,##0.00");

wb.save("exports/report.xlsx");

Constructors

workbook.excelWorkbook workbook.excelWorkbook(isStreamingWorkbook) ExcelWorkbook

Creates a new, empty workbook with one sheet, Sheet1.

Parameter	Type	Description
isStreamingWorkbook	boolean	true for a streaming workbook, for writing very large files. false for a regular workbook.

const wb = workbook.excelWorkbook(false);

workbook.excelWorkbook workbook.excelWorkbook(fileName, isStreamingWorkbook, password, rowAccessWindowSize) ExcelWorkbook

Opens a workbook from a file. Its first sheet is selected.

Parameter	Type	Description
fileName	string	The path of the .xlsx file.
isStreamingWorkbook	boolean	true for a streaming workbook, for writing very large files. false for a regular workbook.
password	string	Optional. The workbook's password. Not supported for streaming workbooks.
rowAccessWindowSize	number	Optional. For streaming workbooks, how many rows to keep in memory.

const wb = workbook.excelWorkbook("uploads/budget.xlsx", false);

workbook.fromBase64 workbook.fromBase64(base64String, isStreamingWorkbook, password) ExcelWorkbook

Opens a workbook from base64-encoded data. Its first sheet is selected.

Parameter	Type	Description
base64String	string	The workbook, base64-encoded.
isStreamingWorkbook	boolean	true for a streaming workbook, for writing very large files. false for a regular workbook.
password	string	Optional. The workbook's password. Not supported for streaming workbooks.

const wb = workbook.fromBase64(base64Data, false);

Overview

• Rows and columns start at 0, so cell A1 is row 0, column 0.
• The current sheet: reads and writes apply to the current sheet. Change it with selectSheet or createSheet.
• Styling: the setCell methods style a cell that has already been written.
• Closing: workbooks close automatically when the process finishes.

Streaming workbooks

A streaming workbook keeps only a window of rows in memory, so it can write very large files. Rows outside the window can't be read back, so use a regular workbook when you need to read cell values.

Reading formulas

The read methods work out a formula's result. If that fails, they throw an error, unless returnCachedOnError is true, which returns the result Excel last stored instead. The readCached methods only use the stored result, which is faster.

Border styles

Value	Style
0	None
1	Thin
2	Medium
3	Dashed
4	Dotted
5	Thick
6	Double
7	Hairline
8	Medium dashed
9	Dash-dot
10	Medium dash-dot
11	Dash-dot-dot
12	Medium dash-dot-dot
13	Slanted dash-dot

Methods

createSheet createSheet(name)

Adds a sheet and makes it the current sheet.

Parameter	Type	Description
name	string	The sheet's name. It can't already be used in the workbook.

selectSheet selectSheet(name)

Makes a sheet the current sheet.

Parameter	Type	Description
name	string	The sheet's name.

changeSheetName changeSheetName(oldName, newName)

Renames a sheet. The current sheet doesn't change.

Parameter	Type	Description
oldName	string	The sheet's current name.
newName	string	The sheet's new name.

getSheetName getSheetName(index) string

Returns the name of the sheet at a position, starting at 0.

Parameter	Type	Description
index	number	The sheet's position.

getNumberOfSheets getNumberOfSheets() number

Returns how many sheets the workbook has.

writeString writeString(row, column, value)

Writes text to a cell.

Parameter	Type	Description
row	number	The row.
column	number	The column.
value	string	The text.

writeNumber writeNumber(row, column, value, numberFormat)

Writes a number to a cell.

Parameter	Type	Description
row	number	The row.
column	number	The column.
value	number	The number.
numberFormat	string	Optional. An Excel number format, such as "#,##0.00".

writeFormula writeFormula(row, column, formula)

Writes a formula to a cell.

Parameter	Type	Description
row	number	The row.
column	number	The column.
formula	string	The formula, without the leading =, such as "SUM(B2:B10)".

deleteRow deleteRow(rowNumber)

Deletes a row. The rows below don't move up, so it leaves an empty row.

Parameter	Type	Description
rowNumber	number	The row.

copyRange copyRange(srcRange, destRange, copyValues, copyFormulas, copyStyles)

Copies a range of cells to another place on the current sheet.

Parameter	Type	Description
srcRange	string	The range to copy, such as "A1:B2".
destRange	string	Where to copy it. Only its top-left cell is used.
copyValues	boolean	true to copy the values.
copyFormulas	boolean	true to copy the formulas.
copyStyles	boolean	true to copy the styles.

copyRange copyRange(srcSheetName, srcRange, destSheetName, destRange, copyValues, copyFormulas, copyStyles)

Copies a range of cells from one sheet to another.

Parameter	Type	Description
srcSheetName	string	The sheet to copy from.
srcRange	string	The range to copy, such as "A1:B2".
destSheetName	string	The sheet to copy to.
destRange	string	Where to copy it.
copyValues	boolean	true to copy the values.
copyFormulas	boolean	true to copy the formulas.
copyStyles	boolean	true to copy the styles.

evaluateAll evaluateAll()

Recalculates every formula in the workbook. Call it before saving so the stored results are up to date.

readString readString(row, column, returnCachedOnError) string | null

Reads a cell as text. Numbers and booleans are converted to text. Returns null when the cell is empty.

Parameter	Type	Description
row	number	The row.
column	number	The column.
returnCachedOnError	boolean	Optional. true to return the stored result if a formula fails.

readNumber readNumber(row, column, returnCachedOnError) number | null

Reads a cell as a number. Returns null when the cell is empty or holds text.

Parameter	Type	Description
row	number	The row.
column	number	The column.
returnCachedOnError	boolean	Optional. true to return the stored result if a formula fails.

readBoolean readBoolean(row, column, returnCachedOnError) boolean | null

Reads a cell as true or false. Returns null when the cell is empty or isn't a boolean.

Parameter	Type	Description
row	number	The row.
column	number	The column.
returnCachedOnError	boolean	Optional. true to return the stored result if a formula fails.

readDate readDate(row, column, format, returnCachedOnError) string

Reads a date cell as text.

Parameter	Type	Description
row	number	The row.
column	number	The column.
format	string	Optional. The date format, such as "DD/MM/YYYY". Defaults to "YYYY-MM-DD".
returnCachedOnError	boolean	Optional. true to return the stored result if a formula fails.

readCachedString readCachedString(row, column) string

Reads a cell as text, using the result Excel last stored.

Parameter	Type	Description
row	number	The row.
column	number	The column.

readCachedNumber readCachedNumber(row, column) number

Reads a cell as a number, using the result Excel last stored.

Parameter	Type	Description
row	number	The row.
column	number	The column.

toMatrix toMatrix(a1Range, cachedOnly) array[]

Reads a range of the current sheet as an array of rows, each an array of values. Numbers, booleans and text keep their types.

Parameter	Type	Description
a1Range	string	The range, such as "A1:D20". Use "" for every cell with a value.
cachedOnly	boolean	true to use the results Excel last stored, instead of working out formulas. Much faster on large sheets.

toMatrix toMatrix(cachedOnly) array[]

Reads every cell with a value on the current sheet. The same as toMatrix("", cachedOnly).

Parameter	Type	Description
cachedOnly	boolean	true to use the results Excel last stored, instead of working out formulas.

setCellFontColor setCellFontColor(rowNum, colNum, hexColor)

Sets a cell's text colour.

Parameter	Type	Description
rowNum	number	The row.
colNum	number	The column.
hexColor	string	The colour, such as "#FF0000".

setCellBackgroundColor setCellBackgroundColor(rowNum, colNum, hexColor)

Sets a cell's background colour.

Parameter	Type	Description
rowNum	number	The row.
colNum	number	The column.
hexColor	string	The colour, such as "#EEEEEE".

setCellAlignment setCellAlignment(rowNum, colNum, horizontal, vertical)

Sets how a cell's content is aligned.

Parameter	Type	Description
rowNum	number	The row.
colNum	number	The column.
horizontal	string	"left", "center", "right" or "justify". Use "" to leave it as it is.
vertical	string	"top", "center", "bottom" or "justify". Use "" to leave it as it is.

setCellBorder setCellBorder(rowNum, colNum, borderStyle)

Sets the border on all four sides of a cell.

Parameter	Type	Description
rowNum	number	The row.
colNum	number	The column.
borderStyle	number	The border style.

setCellBorderSide setCellBorderSide(rowNum, colNum, borderStyle, side)

Sets the border on one side of a cell.

Parameter	Type	Description
rowNum	number	The row.
colNum	number	The column.
borderStyle	number	The border style.
side	string	"top", "bottom", "left" or "right".

getCellAddress getCellAddress(row, column) string

Returns a cell's address, such as "A1" for row 0, column 0.

Parameter	Type	Description
row	number	The row.
column	number	The column.

getColumnName getColumnName(column) string

Returns a column's letter, such as "A" for 0 and "AA" for 26.

Parameter	Type	Description
column	number	The column.

save save(fileName)

Saves the workbook to a file, replacing it if it exists.

Parameter	Type	Description
fileName	string	The path to save to, such as "exports/report.xlsx".

toBase64 toBase64() string

Returns the workbook, base64-encoded, such as to attach to an email.

close close() optional

Closes the workbook. Workbooks close automatically when the process finishes, so only call this to free memory early.

Examples

Build a styled report

const wb = workbook.excelWorkbook(false);
wb.changeSheetName("Sheet1", "Sales");

const headers = ["Region", "Units", "Revenue"];
headers.forEach((header, column) => {
    wb.writeString(0, column, header);
    wb.setCellBackgroundColor(0, column, "#EEEEEE");
    wb.setCellBorderSide(0, column, 1, "bottom");
});

wb.writeString(1, 0, "North");
wb.writeNumber(1, 1, 120);
wb.writeNumber(1, 2, 5000, "#,##0.00");

wb.writeString(2, 0, "South");
wb.writeNumber(2, 1, 85);
wb.writeNumber(2, 2, 4200, "#,##0.00");

wb.writeString(3, 0, "Total");
wb.writeFormula(3, 2, "SUM(C2:C3)");

wb.evaluateAll();
wb.save("exports/sales.xlsx");

Read a sheet

read.js

const wb = workbook.excelWorkbook("uploads/budget.xlsx", false);
wb.selectSheet("Budget");

for (const row of wb.toMatrix("A2:C4", false)) {
    console.log(row.join(", "));
}

Output

North, 2026, 5000
South, 2026, 4200
East, 2026, 3900

Email a workbook

const wb = workbook.excelWorkbook(false);
wb.writeString(0, 0, "Hello");

new EmailBuilder()
    .to("user@example.com")
    .subject("Report")
    .body("The report is attached.")
    .attachBase64("report.xlsx", wb.toBase64())
    .send();

Related

• workbook.workbookFromQuery
• workbook.columnIndexToName
• EmailBuilder