From 4f743b13b86605c3c6c124331cefc7e7b78a52bf Mon Sep 17 00:00:00 2001
From: SheetJS <dev@sheetjs.com>
Date: Sun, 5 Jun 2022 18:43:44 -0400
Subject: [PATCH] installation
---
docz/docs/02-installation/01-standalone.mdx | 111 ++++++++++++++------
docz/docs/02-installation/02-frameworks.md | 7 +-
docz/docs/02-installation/03-deno.md | 9 +-
docz/docs/02-installation/04-nodejs.md | 11 +-
docz/docs/index.md | 1 +
5 files changed, 90 insertions(+), 49 deletions(-)
diff --git a/docz/docs/02-installation/01-standalone.mdx b/docz/docs/02-installation/01-standalone.mdx
index ea68334..d0a7aff 100644
--- a/docz/docs/02-installation/01-standalone.mdx
+++ b/docz/docs/02-installation/01-standalone.mdx
@@ -24,34 +24,27 @@ The `latest` tag references the latest version and updates with each release:
<script lang="javascript" src="https://cdn.sheetjs.com/xlsx-latest/package/dist/xlsx.full.min.js"></script>
```
-**For production use, scripts should be downloaded and added to a public folder
-alongside other scripts.**
-<details>
- <summary><b>Download using Bower</b> (click to show)</summary>
+## Browser Scripts
-[Bower](https://bower.io/) plays nice with the CDN tarballs:
+`xlsx.full.min.js` is the complete standalone script. It includes support for
+reading and writing many spreadsheet formats.
-<pre><code parentName="pre" {...{"className": "language-bash"}}>{`\
-$ npx bower install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
+<pre><code parentName="pre" {...{"className": "language-html"}}>{`\
+<!-- use xlsx.full.min.js from version ${current} -->
+<script lang="javascript" src="https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js"></script>`}
</code></pre>
-Bower will place the standalone scripts in `bower_components/js-xlsx/dist/`
-</details>
-
-<details>
- <summary><b>Browser builds</b> (click to show)</summary>
-
-The complete single-file version is generated at `dist/xlsx.full.min.js`
-
-`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)
- no support for XLSB / XLS / Lotus 1-2-3 / SpreadsheetML 2003 / Numbers
- node stream utils removed
-These scripts are also available on the CDN:
+<details><summary><b>How to integrate the mini build</b> (click to show)</summary>
+
+Replace references to `xlsx.full.min.js` with `xlsx.mini.min.js`. Starting from
+scratch, a single script tag should be added at the top of the HTML page:
<pre><code parentName="pre" {...{"className": "language-html"}}>{`\
<!-- use xlsx.mini.min.js from version ${current} -->
@@ -60,14 +53,22 @@ These scripts are also available on the CDN:
</details>
-<details>
- <summary><b>Internet Explorer and ECMAScript 3 Compatibility</b> (click to show)</summary>
+### Internet Explorer and Older Browsers
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.
+ECMAScript 3 language dialect. A "shim" script provides implementations of
+functions for older browsers and environments.
-To use the shim, add the shim before the script tag that loads `xlsx.js`:
+<div>Due to SSL compatibility issues, older versions of IE will not be able to
+use the CDN scripts directly. They should be downloaded and saved to a public
+directory in the site:
+<ul>
+<li>Standalone: <a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.mini.min.js`}>https://cdn.sheetjs.com/xlsx-{current}/package/dist/xlsx.mini.min.js</a></li>
+<li>Shim: <a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/shim.min.js`}>https://cdn.sheetjs.com/xlsx-{current}/package/dist/shim.min.js</a></li>
+</ul>
+</div>
+
+Add a `script` reference to the shim before the script tag that loads `xlsx.js`:
```html
<!-- add the shim first -->
@@ -76,18 +77,26 @@ To use the shim, add the shim before the script tag that loads `xlsx.js`:
<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.
+### Web Workers
-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.
+The standalone scripts can be loaded using `importScripts` at the top of the
+worker scripts:
-</details>
+<pre><code parentName="pre" {...{"className": "language-js"}}>{`\
+importScripts("https://cdn.sheetjs.com/xlsx-${current}/package/dist/shim.min.js");
+importScripts("https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js");`}
+</code></pre>
-<details>
- <summary><b>ECMAScript Module Imports in a SCRIPT TAG</b> (click to show)</summary>
+
+## ECMAScript Module Imports in a SCRIPT TAG
+
+:::caution
+
+This section refers to imports using `script type="module"`. For imports in
+modern projects using Webpack or React or Angular or Vue, the installation is
+described [in the next section](./frameworks).
+
+:::
The ECMAScript Module build is saved to `xlsx.mjs` and can be directly added to
a page with a `script` tag using `type="module"`:
@@ -98,7 +107,7 @@ import { read, writeFileXLSX } from "https://cdn.sheetjs.com/xlsx-${current}/pac
</script>`}
</code></pre>
-If XLS support is required, `cpexcel.full.js` must be manually imported:
+If XLS support is required, `cpexcel.full.mjs` must be manually imported:
<pre><code parentName="pre" {...{"className": "language-html"}}>{`\
<script type="module">
@@ -109,4 +118,40 @@ set_cptable(cptable);
</script>`}
</code></pre>
-</details>
\ No newline at end of file
+Dynamic imports with `import()` can be used in data export scenarios. This
+example will download the library only when the export button is pressed:
+
+<pre><code parentName="pre" {...{"className": "language-html"}}>{`\
+<button id="xport">Export</button>
+<script type="module">
+xport.addEventListener("click", async() => {
+
+ /* dynamically import the library in the event listener */
+ // highlight-next-line
+ const XLSX = await import("https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs");
+
+ 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.writeFile(wb, "SheetJSESMTest.xlsx");
+});
+</script>`}
+</code></pre>
+
+
+## Bower
+
+:::caution
+
+Bower is deprecated and the maintainers recommend using other tools.
+
+:::
+
+
+[Bower](https://bower.io/) plays nice with the CDN tarballs:
+
+<pre><code parentName="pre" {...{"className": "language-bash"}}>{`\
+$ npx bower install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
+</code></pre>
+
+Bower will place the standalone scripts in `bower_components/js-xlsx/dist/`
diff --git a/docz/docs/02-installation/02-frameworks.md b/docz/docs/02-installation/02-frameworks.md
index aa0170b..f97625e 100644
--- a/docz/docs/02-installation/02-frameworks.md
+++ b/docz/docs/02-installation/02-frameworks.md
@@ -39,10 +39,9 @@ Once installed, the library can be imported under the name `xlsx`:
import { read, writeFileXLSX } from "xlsx";
```
-<details>
- <summary><b>XLS Codepage support</b> (click to show)</summary>
+## XLS Support
-If XLS support is required, `cpexcel.full.js` must be manually imported:
+If XLS support is required, `cpexcel.full.mjs` must be manually imported:
```js
/* load the codepage support library for extended support with older formats */
@@ -50,5 +49,3 @@ import { set_cptable } from "xlsx";
import * as cptable from 'xlsx/dist/cpexcel.full.mjs';
set_cptable(cptable);
```
-
-</details>
\ No newline at end of file
diff --git a/docz/docs/02-installation/03-deno.md b/docz/docs/02-installation/03-deno.md
index 6a1c83c..8b54763 100644
--- a/docz/docs/02-installation/03-deno.md
+++ b/docz/docs/02-installation/03-deno.md
@@ -17,15 +17,14 @@ Using the URL imports, `deno run` will automatically download scripts and types:
import * as XLSX from 'https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs';`}
</code></pre>
-<details>
- <summary><b>XLS Codepage support</b> (click to show)</summary>
+The `@deno-types` comment instructs Deno to use the type definitions.
-If XLS support is required, `cpexcel.full.js` must be manually imported:
+## XLS Support
+
+If XLS support is required, `cpexcel.full.mjs` must be manually imported:
<pre><code parentName="pre" {...{"className": "language-ts"}}>{`\
/* load the codepage support library for extended support with older formats */
import * as cptable from 'https://cdn.sheetjs.com/xlsx-${current}/package/dist/cpexcel.full.mjs';
XLSX.set_cptable(cptable);`}
</code></pre>
-
-</details>
\ No newline at end of file
diff --git a/docz/docs/02-installation/04-nodejs.md b/docz/docs/02-installation/04-nodejs.md
index 465843f..bce55ba 100644
--- a/docz/docs/02-installation/04-nodejs.md
+++ b/docz/docs/02-installation/04-nodejs.md
@@ -13,13 +13,9 @@ import TabItem from '@theme/TabItem';
Tarballs are available on <https://cdn.sheetjs.com>.
-<div>Each individual version can be referenced using a similar URL pattern.
-
+<div>Each individual version can be referenced using a similar URL pattern.<br/>
<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>
-<https://cdn.sheetjs.com/xlsx-latest/xlsx-latest.tgz> is a link to the latest
-version and will refresh on each release.
-
## Installation
Tarballs can be directly installed using a package manager:
@@ -76,6 +72,8 @@ 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 filesystem access:
@@ -83,6 +81,8 @@ for streams and filesystem 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:
@@ -101,4 +101,3 @@ XLSX.stream.set_readable(Readable);
import * as cpexcel from 'xlsx/dist/cpexcel.full.mjs';
XLSX.set_cptable(cpexcel);
```
-
diff --git a/docz/docs/index.md b/docz/docs/index.md
index 217c568..f2a9a1f 100644
--- a/docz/docs/index.md
+++ b/docz/docs/index.md
@@ -9,6 +9,7 @@ hide_table_of_contents: true
[](https://github.com/SheetJS/sheetjs/actions)
[](https://snyk.io/test/github/SheetJS/sheetjs)
[](https://cdn.sheetjs.com/)
+[](https://github.com/SheetJS/sheetjs)
SheetJS Community Edition offers battle-tested open-source solutions for
extracting useful data from almost any complex spreadsheet and generating new