Skip to main content

NodeJS

Package tarballs are available on https://cdn.sheetjs.com.

https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz is the URL for version 0.20.3

Installation​

Tarballs can be directly installed using a package manager:

yarn remove xlsx
yarn add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz

Newer releases of Yarn may throw an error:

Usage Error: It seems you are trying to add a package using a https:... url; we now require package names to be explicitly specified.
Try running the command again with the package name prefixed: yarn add my-package@https:...

The workaround is to prepend the URL with xlsx@:

yarn add xlsx@https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz

Watch the repo or subscribe to the RSS feed to be notified when new versions are released!

Snyk Bugs

Snyk security tooling may report errors involving "Prototype Pollution":

Prototype Pollution [Medium Severity][https://security.snyk.io/vuln/SNYK-JS-XLSX-5457926]

As noted in the Snyk report:

The issue is resolved in version 0.19.3

Snyk is falsely reporting vulnerabilities. It is a bug in the Snyk tooling.

Until Snyk fixes the bugs, the official recommendation is to suppress the warning.

Legacy Endpoints​

Older releases are technically available on the public npm registry as xlsx, but the registry is out of date. The latest version on that registry is 0.18.5

This is a known registry bug

The SheetJS CDN https://cdn.sheetjs.com/ is the authoritative source for SheetJS modules.

For existing projects, the easiest approach is to uninstall and reinstall:

yarn remove xlsx
yarn add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz

When the xlsx library is a dependency of a dependency, the overrides field in package.json can control module resolution:

package.json
{
  "overrides": {
    "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
  }
}

Vendoring​

For general stability, making a local copy of SheetJS modules ("vendoring") is strongly recommended. Vendoring decouples projects from SheetJS infrastructure.

  1. Remove any existing dependency on a project named xlsx:
yarn remove xlsx

  1. Download the tarball (xlsx-0.20.3.tgz) for the desired version. The current version is available at https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz

  1. Create a vendor subfolder at the root of your project and move the tarball to that folder. Add it to your project repository.

  2. Install the tarball using a package manager:

yarn add file:vendor/xlsx-0.20.3.tgz

Newer releases of Yarn may throw an error:

Usage Error: The file:vendor/xlsx-0.20.3.tgz string didn't match the required format (package-name@range). Did you perhaps forget to explicitly reference the package name?

The workaround is to prepend the URI with xlsx@:

yarn add xlsx@file:vendor/xlsx-0.20.3.tgz

The package will be installed and accessible as xlsx.

Usage​

The package supports CommonJS require and ESM import module systems.

It is strongly recommended to use CommonJS in NodeJS.

CommonJS require​

By default, the module supports require and it will automatically add support for encodings, streams and file system access:

var XLSX = require("xlsx");

ESM import​

The package also ships with xlsx.mjs, a script compatible with the ECMAScript module system. When using the ESM build in NodeJS, some dependencies must be loaded manually.

Filesystem Operations​

The set_fs method accepts a fs instance for reading and writing files using readFile and writeFile:

import * as XLSX from 'xlsx';

/* load 'fs' for readFile and writeFile support */
import * as fs from 'fs';
XLSX.set_fs(fs);

Stream Operations​

The set_readable method accepts a stream.Readable instance for use in stream methods including XLSX.stream.to_csv:

import * as XLSX from 'xlsx';

/* load 'stream' for stream support */
import { Readable } from 'stream';
XLSX.stream.set_readable(Readable);

Encoding Support​

The set_cptable method accepts an instance of the SheetJS codepage library for use in legacy file format processing. The cpexcel.full.mjs script must be manually loaded. xlsx/dist/cpexcel.full.mjs can be imported:

import * as XLSX from 'xlsx';

/* load the codepage support library for extended support with older formats  */
import * as cpexcel from 'xlsx/dist/cpexcel.full.mjs';
XLSX.set_cptable(cpexcel);

NextJS​

fs cannot be imported from the top level in NextJS pages. This will not work:

/* it is safe to import the library from the top level */
import { readFile, utils, set_fs } from 'xlsx';
/* it is not safe to import 'fs' from the top level ! */
import * as fs from 'fs'; // this import will fail
set_fs(fs);

For server-side file processing, fs should be loaded with a dynamic import within a lifecycle function:

index.js
/* it is safe to import the library from the top level */
import { readFile, utils, set_fs } from 'xlsx';
import { join } from 'path';
import { cwd } from 'process';

export async function getServerSideProps() {
  set_fs(await import("fs")); // dynamically import 'fs' in `getServerSideProps`
  const wb = readFile(join(cwd(), "public", "sheetjs.xlsx"));
  // ...
}

The NextJS demo includes complete examples.