Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
xlsx
✓ import xlsx from 'node-xlsx';
✗ import { xlsx } from 'node-xlsx'; // Incorrect named import for default export
const xlsx = require('node-xlsx'); // In CommonJS, default export requires '.default'
The library primarily exposes a default export for its main functionality. For CommonJS, you must access the `.default` property.
parse
✓ import xlsx from 'node-xlsx';
const parsedData = xlsx.parse(bufferOrPath);
✗ import { parse } from 'node-xlsx'; // 'parse' is a method of the default export, not a named export.
The `parse` function is a method exposed by the default `xlsx` object, not a direct named export from the module itself.
build
✓ import xlsx from 'node-xlsx';
const buffer = xlsx.build(data);
✗ import { build } from 'node-xlsx'; // 'build' is a method of the default export, not a named export.
The `build` function is a method exposed by the default `xlsx` object, not a direct named export from the module.
WorkSheet
✓ import type { WorkSheet } from 'node-xlsx';
For TypeScript users, type definitions are available for structures like `WorkSheet` to ensure type safety.
This quickstart demonstrates how to create a simple Excel file, then parse its contents both from a buffer and directly from a file path, and finally build another Excel file with custom column widths using `node-xlsx`.
import xlsx from 'node-xlsx';
import fs from 'node:fs';
const filePath = './myFile.xlsx';
// Create a dummy Excel file for parsing example
const dataToBuild = [
[1, 2, 3],
[true, false, null, 'sheetjs'],
['foo', 'bar', new Date('2014-02-19T14:30Z'), '0.3']
];
const bufferToSave = xlsx.build([{name: 'Test Sheet', data: dataToBuild}]);
fs.writeFileSync(filePath, bufferToSave);
console.log('Dummy Excel file created at', filePath);
// 1. Parse an xlsx file from a buffer
const workSheetsFromBuffer = xlsx.parse(fs.readFileSync(filePath));
console.log('Parsed from buffer:', JSON.stringify(workSheetsFromBuffer, null, 2));
// 2. Parse an xlsx file directly from a file path
const workSheetsFromFile = xlsx.parse(filePath);
console.log('Parsed from file path:', JSON.stringify(workSheetsFromFile, null, 2));
// 3. Build an xlsx file with custom options and save it
const complexData = [
['Header A', 'Header B'],
['Value 1', 'Longer Value 2'],
['Short', 'Another Value']
];
const sheetOptions = {'!cols': [{wch: 10}, {wch: 25}]}; // Custom column widths
const mergedBuffer = xlsx.build([{
name: 'Custom Sheet',
data: complexData,
options: sheetOptions
}]);
const outputFilePath = './customOutput.xlsx';
fs.writeFileSync(outputFilePath, mergedBuffer);
console.log('Custom Excel file created at', outputFilePath);
// Clean up dummy file (optional)
fs.unlinkSync(filePath);
fs.unlinkSync(outputFilePath);
console.log('Cleaned up dummy files.');
Debug
Known issues
gotchaAttempting to merge the same cell multiple times or defining overlapping merge ranges within a single sheet will result in a corrupted XLSX file that cannot be opened. Ensure merge ranges are distinct and do not conflict.fixReview your sheet options for '!merges' and ensure each range is unique and non-overlapping. Test generated files with an Excel viewer to confirm integrity.
affects: >=0.1.0
breakingThe underlying 'xlsx' (SheetJS) package has a history of security vulnerabilities in older versions published on npm (e.g., DoS via memory/CPU consumption, Prototype Pollution in versions up to 0.19.2). SheetJS officially moved away from npm, leaving the 'xlsx' package on npm unmaintained and potentially insecure. While node-xlsx actively bumps its internal dependency to address this, direct usage or reliance on older node-xlsx versions might expose applications to these vulnerabilities.fixAlways use the latest stable version of `node-xlsx` to ensure you benefit from the most recent, securely bundled `xlsx` dependency. Avoid installing `xlsx` directly from npm as a standalone package alongside `node-xlsx` due to the unmaintained status of `xlsx` on npm.
affects: <=0.22.0 (and potentially newer if the internal 'xlsx' dependency is not up-to-date with SheetJS's recommended secure version)
gotchaWhen using `require()` in CommonJS modules, `node-xlsx` must be imported via `require('node-xlsx').default` because it primarily exports its API as a default ES Module export. Simply using `require('node-xlsx')` will result in an object that does not expose the `parse` or `build` methods directly, leading to runtime errors.fixFor CommonJS, change `const xlsx = require('node-xlsx');` to `const xlsx = require('node-xlsx').default;` or migrate to ES Modules with `import xlsx from 'node-xlsx';`. affects: >=0.1.0
Errors
Common errors & fixes
TypeError: xlsx.parse is not a function
In a CommonJS environment, the default ES module export of `node-xlsx` was not accessed correctly, leading to the `xlsx` object not containing the expected methods.
fixIf using `require()`, change `const xlsx = require('node-xlsx');` to `const xlsx = require('node-xlsx').default;`. Your .xlsx file is corrupted and cannot be opened.
This error often occurs when `node-xlsx` generates a file with invalid sheet options, most commonly due to incorrectly specified cell merges that are overlapping or duplicate.
fixCarefully review the `!merges` property in your sheet options, ensuring that each merge range is distinct and does not conflict with others. Test with simpler merge configurations first.
NPM audit reports critical vulnerabilities for 'xlsx' package
`node-xlsx` depends on `xlsx`, and older versions of the `xlsx` package on npm are known to have security vulnerabilities and are no longer maintained by SheetJS on the npm registry.
fixEnsure you are using the very latest version of `node-xlsx` (`npm install node-xlsx@latest`). The `node-xlsx` maintainers actively update their internal `xlsx` dependency to mitigate these risks. Avoid installing `xlsx` directly.
Audit
Dependencies
xlsxrequiredCore dependency for Excel parsing and building logic. node-xlsx wraps its functionality.