docs.sheetjs.com/docz/docs/02-getting-started/01-installation/03-nodejs.md
2023-07-26 22:59:29 -04:00

5.4 KiB

pagination_prev pagination_next sidebar_position sidebar_custom_props
getting-started/index getting-started/examples/index 3
summary
Server-side and other frameworks using NodeJS modules

import current from '/version.js'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock';

NodeJS

Tarballs are available on https://cdn.sheetjs.com.

https://cdn.sheetjs.com/xlsx-{current}/xlsx-{current}.tgz is the URL for version {current}

Installation

Tarballs can be directly installed using a package manager:

{`\ npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} {`\ pnpm install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} {`\ yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}

:::tip pass

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

:::

:::warning

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

https://cdn.sheetjs.com/ is the authoritative source for SheetJS scripts.

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

{`\ npm rm --save xlsx npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} {`\ pnpm rm xlsx pnpm install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} {`\ yarn remove xlsx yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}

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

{\ { // highlight-start "overrides": { "xlsx": "https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz" } // highlight-end }}

:::

Vendoring

For general stability, "vendoring" modules is the recommended approach:

1) Download the tarball (xlsx-{current}.tgz) for the desired version. The current version is available at https://cdn.sheetjs.com/xlsx-{current}/xlsx-{current}.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:

{`\ npm i --save file:vendor/xlsx-${current}.tgz`} {`\ pnpm install file:vendor/xlsx-${current}.tgz`} {`\ yarn add file:vendor/xlsx-${current}.tgz`}

The package will be installed and accessible as xlsx.

Usage

CommonJS require

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

var XLSX = require("xlsx");

ESM import

The module also ships with xlsx.mjs for use with import. The mjs version does not automatically load native node modules, so they must be added manually:

import * as XLSX from 'xlsx';

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

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

/* 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

:::warning

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 ! */
// highlight-next-line
import * as fs from 'fs'; // this import will fail
set_fs(fs);

:::

fs should be loaded with a dynamic import within a lifecycle function:

/* 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() {
// highlight-next-line
  set_fs(await import("fs")); // dynamically import 'fs' in `getServerSideProps`
  const wb = readFile(join(cwd(), "public", "sheetjs.xlsx"));
  // ...
}

The NextJS demo includes complete examples.