docs.sheetjs.com/docz/docs/02-installation/04-nodejs.md

138 lines
4.1 KiB
Markdown
Raw Normal View History

2022-05-16 03:26:04 +00:00
---
sidebar_position: 4
sidebar_custom_props:
summary: Server-side and other frameworks using NodeJS modules
---
import current from '/version.js';
# NodeJS
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Tarballs are available on <https://cdn.sheetjs.com>.
2022-06-05 22:43:44 +00:00
<div>Each individual version can be referenced using a similar URL pattern.<br/>
2022-05-16 03:26:04 +00:00
<a href={`https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}>https://cdn.sheetjs.com/xlsx-{current}/xlsx-{current}.tgz</a> is the URL for {current}</div>
## Installation
Tarballs can be directly installed using a package manager:
<Tabs>
<TabItem value="npm" label="npm">
<pre><code parentName="pre" {...{"className": "language-bash"}}>{`\
2022-07-25 23:18:00 +00:00
$ npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
2022-05-16 03:26:04 +00:00
</code></pre>
</TabItem>
<TabItem value="pnpm" label="pnpm">
<pre><code parentName="pre" {...{"className": "language-bash"}}>{`\
2022-07-25 23:18:00 +00:00
$ pnpm install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
2022-05-16 03:26:04 +00:00
</code></pre>
</TabItem>
<TabItem value="yarn" label="Yarn" default>
<pre><code parentName="pre" {...{"className": "language-bash"}}>{`\
2022-07-25 23:18:00 +00:00
$ yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
2022-05-16 03:26:04 +00:00
</code></pre>
</TabItem>
</Tabs>
2022-07-25 23:18:00 +00:00
:::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:
<Tabs>
<TabItem value="npm" label="npm">
<pre><code parentName="pre" {...{"className": "language-bash"}}>{`\
$ npm rm --save xlsx
$ npm i --save file:vendor/xlsx-${current}.tgz`}
</code></pre>
</TabItem>
<TabItem value="pnpm" label="pnpm">
<pre><code parentName="pre" {...{"className": "language-bash"}}>{`\
$ pnpm rm xlsx
$ pnpm install file:vendor/xlsx-${current}.tgz`}
</code></pre>
</TabItem>
<TabItem value="yarn" label="Yarn" default>
<pre><code parentName="pre" {...{"className": "language-bash"}}>{`\
$ yarn remove xlsx
$ yarn add file:vendor/xlsx-${current}.tgz`}
</code></pre>
</TabItem>
</Tabs>
:::
2022-05-16 03:26:04 +00:00
### Vendoring
For general stability, "vendoring" modules is the recommended approach:
<div>1) Download the tarball (<code parentName="pre">xlsx-{current}.tgz</code>) for the desired version. The current
version is available at <a href={`https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}>https://cdn.sheetjs.com/xlsx-{current}/xlsx-{current}.tgz</a></div><br/>
2) Create a `vendor` subdirectory at the root of your project and move the
tarball to that folder. Add it to your project repository.
3) Install the tarball using a package manager:
<Tabs>
<TabItem value="npm" label="npm">
<pre><code parentName="pre" {...{"className": "language-bash"}}>{`\
2022-07-25 23:18:00 +00:00
$ npm i --save file:vendor/xlsx-${current}.tgz`}
2022-05-16 03:26:04 +00:00
</code></pre>
</TabItem>
<TabItem value="pnpm" label="pnpm">
<pre><code parentName="pre" {...{"className": "language-bash"}}>{`\
2022-07-25 23:18:00 +00:00
$ pnpm install file:vendor/xlsx-${current}.tgz`}
2022-05-16 03:26:04 +00:00
</code></pre>
</TabItem>
<TabItem value="yarn" label="Yarn" default>
<pre><code parentName="pre" {...{"className": "language-bash"}}>{`\
2022-07-25 23:18:00 +00:00
$ yarn add file:vendor/xlsx-${current}.tgz`}
2022-05-16 03:26:04 +00:00
</code></pre>
</TabItem>
</Tabs>
The package will be installed and accessible as `xlsx`.
## Usage
2022-06-05 22:43:44 +00:00
#### CommonJS `require`
2022-05-16 03:26:04 +00:00
By default, the module supports `require` and it will automatically add support
for streams and filesystem access:
```js
var XLSX = require("xlsx");
```
2022-06-05 22:43:44 +00:00
#### ESM `import`
2022-05-16 03:26:04 +00:00
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:
```js
import * as XLSX from 'xlsx/xlsx.mjs';
/* 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);
```