From e6fc787cd2417b5ed2d9d768a66041dcaf2d38b5 Mon Sep 17 00:00:00 2001 From: SheetJS Date: Tue, 9 May 2023 04:08:01 -0400 Subject: [PATCH] requirejs --- docz/docs/03-demos/01-frontend/08-bundler.md | 333 ++++++++++++++++--- docz/docs/03-demos/06-desktop/09-cli.md | 139 ++++++-- 2 files changed, 395 insertions(+), 77 deletions(-) diff --git a/docz/docs/03-demos/01-frontend/08-bundler.md b/docz/docs/03-demos/01-frontend/08-bundler.md index 4dfbcf3..f519073 100644 --- a/docz/docs/03-demos/01-frontend/08-bundler.md +++ b/docz/docs/03-demos/01-frontend/08-bundler.md @@ -46,6 +46,12 @@ Web Worker scripts can be bundled using the same approach.
Complete Example (click to show) +:::note + +This demo was last tested on 2023 May 07 against Browserify `17.0.0` + +::: + 1) Install the tarball using a package manager: @@ -72,6 +78,12 @@ yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} - [`index.html`](pathname:///browserify/index.html) - [`xlsxworker.js`](pathname:///browserify/xlsxworker.js) +```bash +curl -LO https://docs.sheetjs.com/browserify/app.js +curl -LO https://docs.sheetjs.com/browserify/index.html +curl -LO https://docs.sheetjs.com/browserify/xlsxworker.js +``` + 3) Bundle the scripts: ```bash @@ -98,6 +110,12 @@ local testing, a bundled script can save tens of milliseconds per run.
Complete Example (click to show) +:::note + +This demo was last tested on 2023 May 07 against Bun `0.5.9` + +::: + 1) Install the tarball using a package manager: @@ -190,6 +208,12 @@ Both the `node` and `browser` platforms work out of the box.
Complete Example (click to show) +:::note + +This demo was last tested on 2023 May 07 against esbuild `0.17.18` + +::: + @@ -259,7 +283,7 @@ writeFileXLSX(workbook, "Presidents.xlsx"); 4) Create bundle: ```bash -npx esbuild esbrowser.js --bundle --outfile=esb.browser.js +npx esbuild@0.17.18 esbrowser.js --bundle --outfile=esb.browser.js ``` 5) Start a local HTTP server, then go to `http://localhost:8080/` @@ -335,7 +359,7 @@ writeFile(workbook, "Presidents.xlsx"); 3) Create bundle: ```bash -npx esbuild esbnode.js --bundle --platform=node --outfile=esb.node.js +npx esbuild@0.17.18 esbnode.js --bundle --platform=node --outfile=esb.node.js ``` 4) Run the bundle: @@ -362,6 +386,12 @@ bug. Upgrade to Parcel version 1.5.0 or later.
Complete Example (click to show) +:::note + +This demo was last tested on 2023 May 07 against parcel `2.8.3` + +::: + This demo follows the [Presidents Example](/docs/getting-started/example). 1) Save the following to `index.html`: @@ -434,7 +464,7 @@ yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} 3) Run the Parcel CLI tool: ```bash -npx -y parcel index.html +npx -y parcel@2.8.3 index.html ``` 4) Access the page listed in the output (typically `http://localhost:1234`) and @@ -472,28 +502,165 @@ CDN, uses it to load the standalone script from the SheetJS CDN, and uses the The `r.js` optimizer also supports the standalone scripts. +
Complete Example (click to show) + +:::note + +This demo was last tested on 2023 May 07 against RequireJS `2.3.3` + +::: + +:::caution + +The `r.js` optimizer does not support ES6 syntax including arrow functions and +the `async` keyword! The demo JS code uses traditional functions. + +::: + +0) Download the standalone build: + +{`\ +curl -LO https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js`} + + +1) Save the following to `index.html`: + +```html title="index.html" + + + + +

SheetJS Presidents Demo

+ + + + + + +``` + +2) Save the following to `SheetJSRequire.js`: + +```js title="SheetJSRequire.js" +require(["xlsx"], function(XLSX) { + document.getElementById("xport").addEventListener("click", function() { + /* fetch JSON data and parse */ + var url = "https://sheetjs.com/data/executive.json"; + fetch(url).then(function(res) { return res.json(); }).then(function(raw_data) { + + /* filter for the Presidents */ + var prez = raw_data.filter(function(row) { return row.terms.some(function(term) { return term.type === "prez"; }); }); + + /* flatten objects */ + var rows = prez.map(function(row) { return { + name: row.name.first + " " + row.name.last, + birthday: row.bio.birthday + }; }); + + /* generate worksheet and workbook */ + var worksheet = XLSX.utils.json_to_sheet(rows); + var workbook = XLSX.utils.book_new(); + XLSX.utils.book_append_sheet(workbook, worksheet, "Dates"); + + /* fix headers */ + XLSX.utils.sheet_add_aoa(worksheet, [["Name", "Birthday"]], { origin: "A1" }); + + /* calculate column width */ + var max_width = rows.reduce(function(w, r) { return Math.max(w, r.name.length); }, 10); + worksheet["!cols"] = [ { wch: max_width } ]; + + /* create an XLSX file and try to save to Presidents.xlsx */ + XLSX.writeFileXLSX(workbook, "Presidents.xlsx"); + }); + }); +}); +``` + +3) Start a local HTTP server, then go to `http://localhost:8080/` + +```bash +npx http-server . +``` + +Click on "Click here to export" to generate a file. + +4) Create `build.js` configuration for the optimizer: + +```js title="build.js" +({ + baseUrl: ".", + name: "SheetJSRequire", + paths: { + xlsx: "./xlsx.full.min" + }, + out: "SheetJSRequire.min.js" +}); +``` + +5) Run the `r.js` optimizer to create `SheetJSRequire.min.js`: + +```bash +npx -p requirejs@2.3.3 r.js -o build.js +``` + +6) Save the following to `optimized.html`: + +```html title="optimized.html" + + + + +

SheetJS Presidents Demo

+ + + + + +``` + +7) Open `http://localhost:8080/optimized.html` + +Click on "Click here to export" to generate a file. + +
+ ## Rollup Rollup requires `@rollup/plugin-node-resolve` to support NodeJS modules:
Complete Example (click to show) +:::note + +This demo was last tested on 2023 May 07 against Rollup 3.21.5 + +::: + 1) Install the tarball using a package manager: {`\ -npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} rollup @rollup/plugin-node-resolve +npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} rollup@3.21.5 @rollup/plugin-node-resolve {`\ -pnpm install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} rollup @rollup/plugin-node-resolve +pnpm install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} rollup@3.21.5 @rollup/plugin-node-resolve {`\ -yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} rollup @rollup/plugin-node-resolve +yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} rollup@3.21.5 @rollup/plugin-node-resolve @@ -572,6 +739,12 @@ Snowpack works with no caveats.
Complete Example (click to show) +:::note + +This demo was last tested on 2023 May 07 against Snowpack `3.8.8` + +::: + 1) Install the tarball using a package manager: @@ -652,7 +825,7 @@ Unlike other bundlers, Snowpack requires a full page including `HEAD` element. 4) Build for production: ```bash -npx snowpack build +npx snowpack@3.8.8 build ``` 5) Start a local HTTP server, then go to `http://localhost:8080/` @@ -669,24 +842,37 @@ Click on "Click here to export" to generate a file. SWC provides `spack` for bundling scripts. +:::warning + +When this demo was last tested, there was a bug affecting 1.2.247 and 1.3 . It +is strongly recommended to use `@swc/core@1.2.245` until the bug is fixed. + +::: +
Complete Example (click to show) +:::note + +This demo was last tested on 2023 May 07 against SWC 1.2.246 + +::: + 1) Install the dependencies using a package manager: {`\ -npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} regenerator-runtime @swc/cli @swc/core +npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} regenerator-runtime @swc/cli @swc/core@1.2.246 {`\ -pnpm install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} regenerator-runtime @swc/cli @swc/core +pnpm install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} regenerator-runtime @swc/cli @swc/core@1.2.246 {`\ -yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} regenerator-runtime @swc/cli @swc/core +yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} regenerator-runtime @swc/cli @swc/core@1.2.246 @@ -775,7 +961,7 @@ This command will create the script `lib/web.js` 6) Start a local HTTP server, then go to `http://localhost:8080/` ```bash -npx http-server build/ +npx http-server ``` Click on "Click here to export" to generate a file. @@ -887,6 +1073,12 @@ SystemJS.config({ +:::note + +This demo was last tested on 2023 May 07 against SystemJS 0.20.16 + +::: + The [Live demo](pathname:///systemjs/systemjs.html) loads SystemJS from the CDN, uses it to load the standalone script from the SheetJS CDN and emulate a `require` implementation when loading [`main.js`](pathname:///systemjs/main.js) @@ -896,10 +1088,17 @@ a `require` implementation when loading [`main.js`](pathname:///systemjs/main.js +:::note + +This demo was last tested on 2023 May 07 against SystemJS 0.19.47 + +::: + 1) Install the dependencies: {`\ -npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz systemjs@0.19`} +npm init -y +npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz systemjs@0.19.47`} 2) Save the following script to `SheetJSystem.js`: @@ -976,18 +1175,20 @@ ViteJS is compatible with SheetJS versions starting from 0.18.10.
Complete Example (click to show) +:::note + +This demo was last tested on 2023 May 07 against ViteJS `4.3.5` + +::: + 1) Create a new ViteJS project: ``` -npm create vite@latest -cd sheetjs-vite # (project name) +npm create vite@latest sheetjs-vite -- --template vue-ts +cd sheetjs-vite npm i ``` -When prompted for **Project Name**, type **`sheetjs-vite`** - -When prompted for **Framework**, select **`vue`** then **`vue-ts`** - 2) Add the SheetJS dependency: {`\ @@ -1044,7 +1245,7 @@ writeFileXLSX(workbook, "Presidents.xlsx"); ``` 4) Run `npm run dev` and test functionality by opening a web browser to -http://localhost:5173/ and clicking the button +`http://localhost:5173/` and clicking the button 5) Run `npx vite build` and verify the generated pages work by running a local web server in the `dist` folder: @@ -1053,7 +1254,7 @@ web server in the `dist` folder: npx http-server dist/ ``` -Access `http://localhost:8080` in your web browser. +Access `http://localhost:8080` in your web browser and click the export button.
@@ -1107,6 +1308,19 @@ import * as XLSX from 'xlsx/dist/xlsx.full.min.js';
Complete Example (click to show) +:::note + +This demo was tested against the following Webpack versions: + +| Version | Date | Required Workarounds | +|:---------|:-----------|:------------------------------------| +| `2.7.0` | 2023-05-07 | Import `xlsx/dist/xlsx.full.min.js` | +| `3.12.0` | 2023-05-07 | Import `xlsx/dist/xlsx.full.min.js` | +| `4.46.0` | 2023-05-07 | Downgrade NodeJS (tested v16.20.0) | +| `5.82.0` | 2023-05-07 | | + +::: + 1) Install the tarball using a package manager: @@ -1133,34 +1347,35 @@ yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} // highlight-next-line import { utils, version, writeFileXLSX } from 'xlsx'; -document.getElementById("xport").addEventListener("click", async() => { -/* fetch JSON data and parse */ -const url = "https://sheetjs.com/data/executive.json"; -const raw_data = await (await fetch(url)).json(); +document.getElementById("xport").addEventListener("click", function() { + /* fetch JSON data and parse */ + var url = "https://sheetjs.com/data/executive.json"; + fetch(url).then(function(res) { return res.json(); }).then(function(raw_data) { -/* filter for the Presidents */ -const prez = raw_data.filter(row => row.terms.some(term => term.type === "prez")); + /* filter for the Presidents */ + var prez = raw_data.filter(function(row) { return row.terms.some(function(term) { return term.type === "prez"; }); }); -/* flatten objects */ -const rows = prez.map(row => ({ - name: row.name.first + " " + row.name.last, - birthday: row.bio.birthday -})); + /* flatten objects */ + var rows = prez.map(function(row) { return { + name: row.name.first + " " + row.name.last, + birthday: row.bio.birthday + }; }); -/* generate worksheet and workbook */ -const worksheet = utils.json_to_sheet(rows); -const workbook = utils.book_new(); -utils.book_append_sheet(workbook, worksheet, "Dates"); + /* generate worksheet and workbook */ + var worksheet = utils.json_to_sheet(rows); + var workbook = utils.book_new(); + utils.book_append_sheet(workbook, worksheet, "Dates"); -/* fix headers */ -utils.sheet_add_aoa(worksheet, [["Name", "Birthday"]], { origin: "A1" }); + /* fix headers */ + utils.sheet_add_aoa(worksheet, [["Name", "Birthday"]], { origin: "A1" }); -/* calculate column width */ -const max_width = rows.reduce((w, r) => Math.max(w, r.name.length), 10); -worksheet["!cols"] = [ { wch: max_width } ]; + /* calculate column width */ + var max_width = rows.reduce(function(w, r) { return Math.max(w, r.name.length); }, 10); + worksheet["!cols"] = [ { wch: max_width } ]; -/* create an XLSX file and try to save to Presidents.xlsx */ -writeFileXLSX(workbook, "Presidents.xlsx"); + /* create an XLSX file and try to save to Presidents.xlsx */ + writeFileXLSX(workbook, "Presidents.xlsx"); + }); }); ``` @@ -1181,6 +1396,19 @@ module.exports = { +:::note + +In Webpack 2.x and 3.x, the import statement must use the standalone build: + +```js title="index.js" +// highlight-next-line +import { utils, version, writeFileXLSX } from 'xlsx/dist/xlsx.full.min.js'; +``` + +::: + +This line must be changed before bundling. + **Webpack 2.x** ```bash @@ -1214,15 +1442,22 @@ version above 4.0 can be pinned by locally installing webpack and the CLI tool. **Webpack 4.x** +:::note + +Webpack 4 is incompatible with Node 18+. When this demo was last tested, NodeJS +was locally downgraded to 16.20.0 + +::: + ```bash -npm i --save webpack@4.x webpack-cli +npm i --save webpack@4.x webpack-cli@4.x npx webpack --mode=production ``` **Webpack 5.x** ```bash -npm i --save webpack@5.x webpack-cli +npm i --save webpack@5.x webpack-cli@5.x npx webpack --mode=production ``` @@ -1263,10 +1498,16 @@ Click on "Click here to export" to generate a file. ## WMR -WMR follows the same structure as Snowpack +WMR works with no caveats.
Complete Example (click to show) +:::note + +This demo was last tested on 2023 May 07 against WMR `3.8.0` + +::: + 1) Install the tarball using a package manager: @@ -1341,7 +1582,7 @@ writeFileXLSX(workbook, "Presidents.xlsx"); 4) Build for production: ```bash -npx wmr build +npx wmr@3.8.0 build ``` 5) Start a local HTTP server in `dist` folder and go to `http://localhost:8080/` diff --git a/docz/docs/03-demos/06-desktop/09-cli.md b/docz/docs/03-demos/06-desktop/09-cli.md index 8639860..7707ffd 100644 --- a/docz/docs/03-demos/06-desktop/09-cli.md +++ b/docz/docs/03-demos/06-desktop/09-cli.md @@ -17,37 +17,6 @@ it is feasible to build command-line tools for various workflows. This demo covers a number of strategies for building standalone processors. The goal is to generate CSV output from an arbitrary spreadsheet file. -## Deno - -`deno compile` generates a standalone executable that includes the entire JS -runtime as well as user JS code. - -When compiling, the `--allow-read` option must be specified to allow the script -to read files from the filesystem with `Deno.readFileSync`. - - can be compiled and run from Deno: - -0) Download the test file : - -```bash -curl -LO https://sheetjs.com/pres.numbers -``` - -1) Test the script with `deno run`: - -```bash -deno run -r --allow-read https://docs.sheetjs.com/cli/sheet2csv.ts pres.numbers -``` - -If this worked, the program will print a CSV of the first worksheet. - -2) Compile and run `sheet2csv`: - -```bash -deno compile -r --allow-read https://docs.sheetjs.com/cli/sheet2csv.ts -./sheet2csv pres.numbers -``` - ## NodeJS There are a few popular tools for compiling NodeJS scripts to CLI programs. @@ -65,8 +34,47 @@ Options: ... ``` +
Tested Deployments (click to show) + +This demo was tested in the following deployments: + +**`pkg`** + +| Architecture | Version | Node Target | Date | +|:-------------|:--------|:------------|:-----------| +| `darwin-x64` | `5.8.1` | `18.5.0` | 2023-05-08 | +| `win32-x64` | `5.8.1` | `18.5.0` | 2023-05-08 | +| `linux-x64` | `5.8.1` | `18.5.0` | 2023-05-08 | + +**`nexe`** + +| Architecture | Version | Node Target | Date | +|:-------------|:-------------|:------------|:-----------| +| `darwin-x64` | `4.0.0-rc.2` | `14.15.3` | 2023-05-08 | +| `win32-x64` | `4.0.0-rc.2` | `14.15.3` | 2023-05-08 | +| `linux-x64` | `4.0.0-rc.2` | `14.15.3` | 2023-05-08 | + +**`boxednode`** + +| Architecture | Version | Node Target | Date | +|:-------------|:--------|:------------|:-----------| +| `darwin-x64` | `2.0.1` | `20.1.0` | 2023-05-08 | +| `linux-x64` | `2.0.1` | `20.1.0` | 2023-05-08 | + +
+ +0) Download the test file : + +```bash +curl -LO https://sheetjs.com/pres.numbers +``` + 1) Download [`xlsx-cli.js`](pathname:///cli/xlsx-cli.js) +```bash +curl -LO https://docs.sheetjs.com/cli/xlsx-cli.js +``` + 2) Install the dependencies: @@ -111,5 +119,74 @@ npx pkg xlsx-cli.js This generates `xlsx-cli-linux`, `xlsx-cli-macos`, and `xlsx-cli-win.exe` . + + + +Run `boxednode`: + +```bash +npx boxednode@2.0.1 -s xlsx-cli.js -t xlsx-cli +``` + + +4) Run the generated program, passing `pres.numbers` as the argument. For +example, on an Intel Mac, `nexe` generates `xlsx-cli` so the command is: + +```bash +./xlsx-cli pres.numbers +``` + +## Deno + +`deno compile` generates a standalone executable that includes the entire JS +runtime as well as user JS code. + +When compiling, the `--allow-read` option must be specified to allow the script +to read files from the filesystem with `Deno.readFileSync`. + + can be compiled and run from Deno. + +
Tested Deployments (click to show) + +This demo was last tested in the following deployments: + +| Architecture | Version | Date | +|:-------------|:---------|:-----------| +| `darwin-x64` | `1.33.2` | 2023-05-08 | +| `win32-x64` | `1.33.2` | 2023-05-08 | +| `linux-x64` | `1.33.2` | 2023-05-08 | + +
+ +0) Download the test file : + +```bash +curl -LO https://sheetjs.com/pres.numbers +``` + +1) Test the script with `deno run`: + +```bash +deno run -r --allow-read https://docs.sheetjs.com/cli/sheet2csv.ts pres.numbers +``` + +If this worked, the program will print a CSV of the first worksheet. + +2) Compile and run `sheet2csv`: + +```bash +deno compile -r --allow-read https://docs.sheetjs.com/cli/sheet2csv.ts +./sheet2csv pres.numbers +``` + +## Dedicated Engines + +The following demos for JS engines produce standalone programs: + +- [ChakraCore](/docs/demos/engines/chakra) +- [Duktape](/docs/demos/engines/duktape) +- [Goja](/docs/demos/engines/goja) +- [JavaScriptCore](/docs/demos/engines/jsc) +- [QuickJS](/docs/demos/engines/quickjs)