sheetjs-clone/docbits/10_install.md

213 lines
6.6 KiB
Markdown
Raw Normal View History

## Getting Started
### Installation
2022-04-16 01:19:21 +00:00
#### Standalone Browser Scripts
2022-02-12 06:31:47 +00:00
2022-04-16 01:19:21 +00:00
Each standalone release script is available at <https://cdn.sheetjs.com/>.
2022-04-25 22:13:46 +00:00
The current version is `0.18.7` and can be referenced as follows:
```html
2022-04-25 22:13:46 +00:00
<!-- use version 0.18.7 -->
<script lang="javascript" src="https://cdn.sheetjs.com/xlsx-0.18.7/package/dist/xlsx.full.min.js"></script>
```
2022-04-16 01:19:21 +00:00
The `latest` tag references the latest version and updates with each release:
2017-09-24 23:40:09 +00:00
2022-04-12 11:59:15 +00:00
```html
<!-- use the latest version -->
<script lang="javascript" src="https://cdn.sheetjs.com/xlsx-latest/package/dist/xlsx.full.min.js"></script>
```
2017-09-24 23:40:09 +00:00
2022-04-16 01:19:21 +00:00
**For production use, scripts should be downloaded and added to a public folder
alongside other scripts.**
2017-09-24 23:40:09 +00:00
<details>
<summary><b>Browser builds</b> (click to show)</summary>
The complete single-file version is generated at `dist/xlsx.full.min.js`
2022-02-26 04:32:40 +00:00
`dist/xlsx.core.min.js` omits codepage library (no support for XLS encodings)
A slimmer build is generated at `dist/xlsx.mini.min.js`. Compared to full build:
- codepage library skipped (no support for XLS encodings)
2022-02-26 04:32:40 +00:00
- no support for XLSB / XLS / Lotus 1-2-3 / SpreadsheetML 2003 / Numbers
- node stream utils removed
2022-04-12 11:59:15 +00:00
These scripts are also available on the CDN:
```html
2022-04-25 22:13:46 +00:00
<!-- use xlsx.mini.min.js from version 0.18.7 -->
<script lang="javascript" src="https://cdn.sheetjs.com/xlsx-0.18.7/package/dist/xlsx.mini.min.js"></script>
2022-04-12 11:59:15 +00:00
```
</details>
2022-04-16 01:19:21 +00:00
[Bower](https://bower.io/search/?q=js-xlsx) will pull the entire repo:
2022-02-12 06:31:47 +00:00
```bash
$ bower install js-xlsx
```
2022-04-16 01:19:21 +00:00
Bower will place the standalone scripts in `bower_components/js-xlsx/dist/`
<details>
<summary><b>Internet Explorer and ECMAScript 3 Compatibility</b> (click to show)</summary>
For broad compatibility with JavaScript engines, the library is written using
ECMAScript 3 language dialect as well as some ES5 features like `Array#forEach`.
Older browsers require shims to provide missing functions.
To use the shim, add the shim before the script tag that loads `xlsx.js`:
```html
<!-- add the shim first -->
<script type="text/javascript" src="shim.min.js"></script>
<!-- after the shim is referenced, add the library -->
<script type="text/javascript" src="xlsx.full.min.js"></script>
```
Due to SSL certificate compatibility issues, it is highly recommended to save
the Standalone and Shim scripts from <https://cdn.sheetjs.com/> and add to a
public directory in the site.
The script also includes `IE_LoadFile` and `IE_SaveFile` for loading and saving
files in Internet Explorer versions 6-9. The `xlsx.extendscript.js` script
bundles the shim in a format suitable for Photoshop and other Adobe products.
</details>
#### ECMAScript Modules
_Browser ESM_
2022-02-14 01:28:13 +00:00
The ECMAScript Module build is saved to `xlsx.mjs` and can be directly added to
2022-04-14 07:27:38 +00:00
a page with a `script` tag using `type="module"`:
2022-02-14 01:28:13 +00:00
```html
<script type="module">
2022-04-25 22:13:46 +00:00
import { read, writeFileXLSX } from "https://cdn.sheetjs.com/xlsx-0.18.7/package/xlsx.mjs";
2022-02-14 01:28:13 +00:00
/* load the codepage support library for extended support with older formats */
2022-04-25 22:13:46 +00:00
import { set_cptable } from "https://cdn.sheetjs.com/xlsx-0.18.7/package/xlsx.mjs";
import * as cptable from 'https://cdn.sheetjs.com/xlsx-0.18.7/package/dist/cpexcel.full.mjs';
2022-02-14 01:28:13 +00:00
set_cptable(cptable);
</script>
```
2022-04-16 01:19:21 +00:00
_Frameworks (Angular, VueJS, React) and Bundlers (webpack, etc)_
The NodeJS package is readily installed from the tarballs:
```bash
2022-04-25 22:13:46 +00:00
$ npm install --save https://cdn.sheetjs.com/xlsx-0.18.7/xlsx-0.18.7.tgz # npm
$ pnpm install --save https://cdn.sheetjs.com/xlsx-0.18.7/xlsx-0.18.7.tgz # pnpm
$ yarn add --save https://cdn.sheetjs.com/xlsx-0.18.7/xlsx-0.18.7.tgz # yarn
2022-04-16 01:19:21 +00:00
```
Once installed, the library can be imported under the name `xlsx`:
2022-02-14 01:28:13 +00:00
```ts
import { read, writeFileXLSX } from "xlsx";
/* 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);
```
2022-04-16 01:19:21 +00:00
#### Deno
2022-02-12 06:31:47 +00:00
2022-04-12 11:59:15 +00:00
`xlsx.mjs` can be imported in Deno:
2022-02-12 06:31:47 +00:00
```ts
2022-04-25 22:13:46 +00:00
// @deno-types="https://cdn.sheetjs.com/xlsx-0.18.7/package/types/index.d.ts"
import * as XLSX from 'https://cdn.sheetjs.com/xlsx-0.18.7/package/xlsx.mjs';
2022-02-13 09:35:34 +00:00
/* load the codepage support library for extended support with older formats */
2022-04-25 22:13:46 +00:00
import * as cptable from 'https://cdn.sheetjs.com/xlsx-0.18.7/package/dist/cpexcel.full.mjs';
2022-02-13 09:35:34 +00:00
XLSX.set_cptable(cptable);
2022-02-12 06:31:47 +00:00
```
2022-04-16 01:19:21 +00:00
#### NodeJS
2022-02-12 06:31:47 +00:00
2022-04-14 07:27:38 +00:00
Tarballs are available on <https://cdn.sheetjs.com>.
2022-04-12 11:59:15 +00:00
2022-04-16 01:19:21 +00:00
Each individual version can be referenced using a similar URL pattern.
2022-04-25 22:13:46 +00:00
<https://cdn.sheetjs.com/xlsx-0.18.7/xlsx-0.18.7.tgz> is the URL for `0.18.7`
2022-04-16 01:19:21 +00:00
2022-04-14 07:27:38 +00:00
<https://cdn.sheetjs.com/xlsx-latest/xlsx-latest.tgz> is a link to the latest
version and will refresh on each release.
2022-04-16 01:19:21 +00:00
_Installation_
2022-04-12 11:59:15 +00:00
Tarballs can be directly installed using a package manager:
```bash
2022-04-25 22:13:46 +00:00
$ npm install https://cdn.sheetjs.com/xlsx-0.18.7/xlsx-0.18.7.tgz # npm
$ pnpm install https://cdn.sheetjs.com/xlsx-0.18.7/xlsx-0.18.7.tgz # pnpm
$ yarn add https://cdn.sheetjs.com/xlsx-0.18.7/xlsx-0.18.7.tgz # yarn
```
2022-04-14 07:27:38 +00:00
For general stability, "vendoring" modules is the recommended approach:
2022-04-25 22:13:46 +00:00
1) Download the tarball (`xlsx-0.18.7.tgz`) for the desired version. The current
version is available at <https://cdn.sheetjs.com/xlsx-0.18.7/xlsx-0.18.7.tgz>
2022-04-14 07:27:38 +00:00
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:
```bash
2022-04-25 22:13:46 +00:00
$ npm install --save file:vendor/xlsx-0.18.7.tgz # npm
$ pnpm install --save file:vendor/xlsx-0.18.7.tgz # pnpm
$ yarn add file:vendor/xlsx-0.18.7.tgz # yarn
```
2022-04-14 07:27:38 +00:00
The package will be installed and accessible as `xlsx`.
2022-04-16 01:19:21 +00:00
_Usage_
By default, the module supports `require` and it will automatically add support
for streams and filesystem access:
2022-02-12 06:31:47 +00:00
```js
var XLSX = require("xlsx");
```
2022-04-16 01:19:21 +00:00
The module also ships with `xlsx.mjs` for use with `import`. The `mjs` version
does not automatically load native node modules:
2022-02-12 06:31:47 +00:00
```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);
2022-02-12 06:31:47 +00:00
/* load the codepage support library for extended support with older formats */
import * as cpexcel from 'xlsx/dist/cpexcel.full.mjs';
XLSX.set_cptable(cpexcel);
```
2022-04-16 01:19:21 +00:00
#### Photoshop and InDesign
2022-02-12 06:31:47 +00:00
2022-04-14 07:27:38 +00:00
`dist/xlsx.extendscript.js` is an ExtendScript build for Photoshop and InDesign.
2022-04-25 22:13:46 +00:00
<https://cdn.sheetjs.com/xlsx-0.18.7/package/dist/xlsx.extendscript.js> is the
2022-04-16 01:19:21 +00:00
current version. After downloading the script, it can be directly referenced
with a `#include` directive:
```extendscript
#include "xlsx.extendscript.js"
```