installation

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>
+## Browser Scripts
-  <summary><b>Download using Bower</b> (click to show)</summary>
 
-[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"}}>{`\
+<pre><code parentName="pre" {...{"className": "language-html"}}>{`\
-$ npx bower install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
+<!-- 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>
+### Internet Explorer and Older Browsers
-  <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`.
+ECMAScript 3 language dialect.  A "shim" script provides implementations of
-Older browsers require shims to provide missing functions.
+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
+### Web Workers
-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
+The standalone scripts can be loaded using `importScripts` at the top of the
-files in Internet Explorer versions 6-9.  The `xlsx.extendscript.js` script
+worker scripts:
-bundles the shim in a format suitable for Photoshop and other Adobe products.
 
-</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>
+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/`

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>
+## XLS Support
-  <summary><b>XLS Codepage support</b> (click to show)</summary>
 
-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>

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>
+The `@deno-types` comment instructs Deno to use the type definitions.
-  <summary><b>XLS Codepage support</b> (click to show)</summary>
 
-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>

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);
 ```
-

docz/docs/index.md

@@ -9,6 +9,7 @@ hide_table_of_contents: true
 [![Build Status](https://img.shields.io/github/workflow/status/sheetjs/sheetjs/Tests:%20node.js)](https://github.com/SheetJS/sheetjs/actions)
 [![Snyk Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/github/SheetJS/sheetjs)](https://snyk.io/test/github/SheetJS/sheetjs)
 [![npm Downloads](https://img.shields.io/npm/dm/xlsx.svg)](https://cdn.sheetjs.com/)
+[![GitHub Repo stars](https://img.shields.io/github/stars/SheetJS/sheetjs?style=social)](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