From 4f743b13b86605c3c6c124331cefc7e7b78a52bf Mon Sep 17 00:00:00 2001 From: SheetJS 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: ``` -**For production use, scripts should be downloaded and added to a public folder -alongside other scripts.** -
- Download using Bower (click to show) +## 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. -
{`\
-$ npx bower install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
+
{`\
+
+`}
 

 
-Bower will place the standalone scripts in `bower_components/js-xlsx/dist/`
-
- -
- Browser builds (click to show) - -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: +
How to integrate the mini build (click to show) + +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: 
{`\
 
@@ -60,14 +53,22 @@ These scripts are also available on the CDN:
-
- Internet Explorer and ECMAScript 3 Compatibility (click to show) +### 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`: +
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: + +
+ +Add a `script` reference to the shim before the script tag that loads `xlsx.js`: ```html @@ -76,18 +77,26 @@ To use the shim, add the shim before the script tag that loads `xlsx.js`: ``` -Due to SSL certificate compatibility issues, it is highly recommended to save -the Standalone and Shim scripts from 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: -
+
{`\
+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");`}
+
-
- ECMAScript Module Imports in a SCRIPT TAG (click to show) + +## 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 `} -If XLS support is required, `cpexcel.full.js` must be manually imported: +If XLS support is required, `cpexcel.full.mjs` must be manually imported: 
{`\
 `}
-
\ 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: + +
{`\
+
+`}
+
+ + +## Bower + +:::caution + +Bower is deprecated and the maintainers recommend using other tools. + +::: + + +[Bower](https://bower.io/) plays nice with the CDN tarballs: + +
{`\
+$ npx bower install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
+
+ +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"; ``` -
- XLS Codepage support (click to show) +## 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); ``` - -
\ 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';`} -
- XLS Codepage support (click to show) +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: 
{`\
 /* 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);`}
- -
\ 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 . -
Each individual version can be referenced using a similar URL pattern. - +
Each individual version can be referenced using a similar URL pattern.
https://cdn.sheetjs.com/xlsx-{current}/xlsx-{current}.tgz is the URL for {current}
- 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 [![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