Registry / serialization / xlsx
library0.0.1jsnpmunverified

SheetJS XLSX is a robust, battle-tested JavaScript library for parsing and writing spreadsheet data in various formats, including XLSX, XLS, CSV, ODS, and more. The current stable version is 0.18.5, with frequent updates addressing new features and bug fixes. It distinguishes itself with extensive format support, compatibility across Node.js and browsers, and first-class TypeScript definitions. The library focuses on data extraction and generation, offering a 'Community Edition' (this `xlsx` package) for core functionalities, while advanced features like styling, formula evaluation, and custom sheet generation are reserved for the commercial 'SheetJS Pro' offering. It's designed to handle complex spreadsheets and work with both legacy and modern software environments, making it a versatile tool for spreadsheet data manipulation.

npm install xlsx
INSTALL
IMPORT
SIG · XLSX
X
xlsx
serializationjavascriptv0.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

XLSX
import * as XLSX from 'xlsx';
import XLSX from 'xlsx'; const XLSX = require('xlsx').default;
The 'xlsx' package uses a namespace import pattern for ESM and returns the full module object for CJS. Direct default import (`import XLSX from 'xlsx'`) is incorrect as there is no default export. CommonJS `require('xlsx').default` also typically results in undefined.
read
import { read } from 'xlsx'; // or import * as XLSX from 'xlsx'; const workbook = XLSX.read(data, options);
const { read } = require('xlsx/dist/xlsx.full.min');
While `read` is a top-level named export, it's often accessed via the `XLSX` namespace (e.g., `XLSX.read`). Some older or specific build setups might use direct paths like `xlsx/dist/...`, but the main package export is preferred for stability and type inference.
utils
import { utils } from 'xlsx'; // or import * as XLSX from 'xlsx'; const data = XLSX.utils.sheet_to_json(worksheet);
import { sheet_to_json } from 'xlsx/utils';
Utility functions are typically nested under the `XLSX.utils` object. Directly importing from `xlsx/utils` might not work or be stable across versions. The `utils` object itself is a named export.
Workbook
import { Workbook, WorkSheet } from 'xlsx';
import { type Workbook } from 'xlsx';
TypeScript types like `Workbook` and `WorkSheet` are directly exported and can be imported using standard named import syntax. The `type` keyword is optional in newer TypeScript versions but not incorrect.

This quickstart demonstrates how to read an existing Excel file, convert its data to JSON, and then create a new Excel file from JSON data using SheetJS in a Node.js environment. It highlights common parsing and writing patterns.

import * as XLSX from 'xlsx'; import * as fs from 'fs'; // Required for Node.js file operations // Define file paths const filePath = 'example.xlsx'; const outputPath = 'users.json'; const newExcelPath = 'products.xlsx'; // Helper to create a dummy Excel file for demonstration const createDummyExcel = () => { const ws = XLSX.utils.json_to_sheet([ { Name: 'Alice', Age: 30, City: 'New York' }, { Name: 'Bob', Age: 24, City: 'Los Angeles' } ]); const wb = XLSX.utils.book_new(); XLSX.utils.book_append_sheet(wb, ws, 'Users'); XLSX.writeFile(wb, filePath); console.log(`Created dummy Excel file: ${filePath}`); }; // Ensure a dummy file exists for reading if (!fs.existsSync(filePath)) { createDummyExcel(); } try { // 1. Read the workbook from a file const workbook = XLSX.readFile(filePath); console.log(`Successfully read workbook from ${filePath}`); // 2. Get the first sheet's name and then the worksheet object const sheetName = workbook.SheetNames[0]; const worksheet = workbook.Sheets[sheetName]; // 3. Convert the worksheet to an array of JSON objects const jsonData = XLSX.utils.sheet_to_json(worksheet); console.log('Converted sheet to JSON:', JSON.stringify(jsonData, null, 2)); // 4. Write the JSON data to a new file fs.writeFileSync(outputPath, JSON.stringify(jsonData, null, 2), 'utf-8'); console.log(`JSON data written to ${outputPath}`); // 5. Create a new workbook from JSON data and write it to an Excel file const newProducts = [ { Product: 'Laptop', Price: 1200, Stock: 50 }, { Product: 'Mouse', Price: 25, Stock: 200 }, { Product: 'Keyboard', Price: 75, Stock: 150 } ]; const newWorksheet = XLSX.utils.json_to_sheet(newProducts); const newWorkbook = XLSX.utils.book_new(); XLSX.utils.book_append_sheet(newWorkbook, newWorksheet, 'Products'); XLSX.writeFile(newWorkbook, newExcelPath); console.log(`New Excel file written to ${newExcelPath}`); } catch (error) { console.error('Error processing Excel file:', error); } // In a browser, file operations would use FileReader and browser APIs like FileSaver.js: /* // Browser Read Example document.getElementById('file-input').addEventListener('change', (event) => { const file = event.target.files[0]; const reader = new FileReader(); reader.onload = (e) => { const data = e.target.result; // ArrayBuffer const workbook = XLSX.read(data, { type: 'array' }); // ... process workbook }; reader.readAsArrayBuffer(file); }); // Browser Write Example (requires FileSaver.js) // const wb = XLSX.utils.book_new(); // ... create workbook // XLSX.writeFile(wb, 'output.xlsx'); */
Debug
Known issues
gotchaThe `xlsx` npm package is the 'Community Edition' of SheetJS, providing core parsing and writing functionality. Advanced features such as spreadsheet styling, advanced formula evaluation, custom charts, images, and pivot tables are exclusively available in the commercial 'SheetJS Pro' offering and are not part of this open-source package.
fix
Review the SheetJS Pro documentation if your application requires advanced spreadsheet features beyond basic data manipulation. Features like formula evaluation (`eval_formulae`) require the Pro version.
affects: >=0.18.0
gotchaProcessing very large spreadsheet files (tens of thousands of rows or complex formatting) can lead to significant memory consumption, potentially causing Node.js applications to exceed memory limits or browser tabs to crash. The library loads the entire workbook into memory by default.
fix
For extremely large files, consider streaming parsers (if available for your format in Pro) or processing data in chunks if possible. For Node.js, increasing the Node.js memory limit (`--max-old-space-size`) might temporarily alleviate issues, but optimization of data handling is generally preferred.
affects: >=0.8
gotchaDate parsing can be inconsistent or require specific handling. Excel stores dates as serial numbers, and `xlsx` can return them as raw numbers or attempt conversion. Incorrect date interpretation is a common issue.
fix
When calling `sheet_to_json`, use options like `cellDates: true` to get Date objects directly or `raw: true` to get raw numbers and perform custom date conversions. Always verify the output format of dates during development.
affects: >=0.8
gotchaWhile `xlsx` works in both Node.js and browser environments, file system operations (like `readFile` or `writeFile`) are Node.js-specific. In a browser, you must use browser-native APIs (e.g., `FileReader` for input, `FileSaver.js` or similar for output) to handle files.
fix
For browser applications, use `XLSX.read(data, { type: 'array' })` with `FileReader` results or `XLSX.writeFile(workbook, filename)` with a helper like `FileSaver.js`. Ensure your build setup correctly handles conditional imports or shims for different environments.
affects: >=0.8
breakingOlder versions (prior to 0.18.x) had less consistent ESM export behavior. While `import * as XLSX from 'xlsx';` is the recommended and stable pattern now, some older examples or bundler configurations might have relied on alternative import styles that are no longer supported or recommended.
fix
Ensure you are using `import * as XLSX from 'xlsx';` for ES Modules and `const XLSX = require('xlsx');` for CommonJS. Update your bundler configuration if necessary to correctly resolve the module structure.
affects: <0.18.0
Errors
Common errors & fixes
Error: Cannot find module 'fs'
Attempting to use Node.js-specific file system functions (`readFile`, `writeFile`) in a browser environment.
fix
For browser environments, use `FileReader` to get file data as an ArrayBuffer for `XLSX.read`, and browser-compatible file saving utilities (e.g., `FileSaver.js`) for `XLSX.writeFile`. The `xlsx` core library itself is universal, but I/O needs environment-specific helpers.
TypeError: XLSX.read is not a function
The `XLSX` module was imported incorrectly, leading to `XLSX` being `undefined` or not containing the expected functions. This often happens with `import XLSX from 'xlsx'` (default import) instead of the namespace import.
fix
Use `import * as XLSX from 'xlsx';` for ES Modules or `const XLSX = require('xlsx');` for CommonJS to ensure the `XLSX` variable correctly holds the module's exports.
Dates are returned as numbers instead of Date objects.
By default, `sheet_to_json` and similar utilities often return raw Excel serial numbers for dates.
fix
Pass `{ cellDates: true }` as an option to `XLSX.utils.sheet_to_json` (or similar utility) to instruct the library to attempt conversion of serial numbers into JavaScript `Date` objects.
RangeError: Array buffer allocation failed
Attempting to process an extremely large spreadsheet file that exceeds the available memory (especially common in Node.js with its default memory limits or in browsers).
fix
Increase Node.js's memory limit via `node --max-old-space-size=4096 script.js` (for 4GB). In browsers, consider optimizing the input file size, splitting processing, or looking into streaming solutions if offered by SheetJS Pro.
Upgrade
Version history
0.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
69 hits · last 30 days
node
64
OpenAI (training)
1
Resources