8.5 KiB
title | pagination_prev | pagination_next | sidebar_position | sidebar_custom_props | ||
---|---|---|---|---|---|---|
Frameworks and Bundlers | getting-started/index | getting-started/examples/index | 2 |
|
import current from '/version.js'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock';
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`}:::caution pass
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-${current}/xlsx-${current}.tgz
}
:::
Once installed, the library can be imported under the name xlsx
:
import { read, writeFileXLSX } from "xlsx";
The "Bundlers" demo includes complete examples.
:::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
:::danger 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, making a local copy of SheetJS modules ("vendoring") is strongly recommended. Vendoring decouples projects from SheetJS infrastructure.
- Remove any existing dependency on a project named
xlsx
:
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"}
{\ curl -o https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz
}
- Create a
vendor
subfolder at the root of your project:
mkdir -p vendor
- Move the tarball from step (1) to the
vendor
folder:
{\ mv xlsx-${current}.tgz vendor
}
- If the project is managed with a version control system, add the tarball to
the source repository. The Git VCS supports the
add
subcommand:
{\ git add vendor/xlsx-${current}.tgz
}
- Install the tarball using a package manager:
:::caution pass
Newer releases of Yarn may throw an error:
{\ Usage Error: The file:vendor/xlsx-${current}.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-${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 complete examples.
Dynamic Imports
Dynamic imports with import()
will only download scripts when they are needed.
:::danger 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);