docs.sheetjs.com/docz/docs/02-getting-started/01-installation/02-frameworks.md
SheetJS 92e3c5aa72 mdx cleanup in preparation for v2
- use autolinks (e.g <https://sheetjs.com> -> https://sheetjs.com)
- move <summary> blocks to separate lines
2024-04-08 00:57:39 -04:00

7.0 KiB

pagination_prev pagination_next sidebar_position sidebar_custom_props
getting-started/index getting-started/examples/index 2
summary
Angular, React, VueJS, Webpack, etc.

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

Frameworks and Bundlers

Each standalone release package is available at https://cdn.sheetjs.com/. The NodeJS package is designed to be used with frameworks and bundlers. It is a proper ECMAScript Module release which can be optimized with developer tools.

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 rm --save xlsx npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} {`\ pnpm rm xlsx pnpm install --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} {`\ yarn remove xlsx yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}

Once installed, the library can be imported under the name xlsx:

import { read, writeFileXLSX } from "xlsx";

The "Bundlers" demo includes examples for specific tools.

:::tip pass

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

:::

:::caution 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

:::warning pass

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:

{`\ npm rm --save xlsx npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} {`\ pnpm rm xlsx pnpm install --save 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. Remove any existing dependency on a project named xlsx:
{`\ npm rm --save xlsx`} {`\ pnpm rm xlsx`} {`\ yarn remove xlsx`}

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 --save file:vendor/xlsx-${current}.tgz`} {`\ yarn add file:vendor/xlsx-${current}.tgz`}

The package will be installed and accessible as xlsx.

Usage

With most frameworks and bundler tools, named imports are recommended:

import { read, utils } from 'xlsx';

Some legacy bundlers require the glob import:

import * as XLSX from 'xlsx';
const { read, utils } = XLSX;

For legacy bundlers that support CommonJS, require will work:

var XLSX = require("xlsx");
var read = XLSX.read, utils = XLSX.utils;

The "Bundlers" demo includes examples for specific tools.

Dynamic Imports

Dynamic imports with import() will only download scripts when they are needed.

:::warning pass

Dynamic import will always download the full contents of the imported scripts!

This is a design flaw in ECMAScript modules

:::

It is strongly recommended to use a wrapper script that imports and re-exports the parts of the SheetJS library that are used in a specific function or page:

/* This wrapper pulls `writeFileXLSX` and `utils` from the SheetJS library */
import { utils, writeFileXLSX } from "xlsx";
export { utils, writeFileXLSX };

A dynamic import of the wrapper script will only load the requested features:

async function export_data() {
  /* dynamically import the SheetJS Wrapper */
  // highlight-next-line
  const XLSX = await import ("./SheetJSWriteWrapper");
  const wb = XLSX.utils.book_new();
  const ws = XLSX.utils.aoa_to_sheet([["a","b","c"],[1,2,3]]);
  XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
  XLSX.writeFileXLSX(wb, "SheetJSDynamicWrapperTest.xlsx");
}

Encoding support

If Encoding support is required, cpexcel.full.mjs must be manually imported:

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