sheetjs/docs.sheetjs.com
1
Fork 4
Code Issues 2 Pull Requests 1 Projects Releases Wiki Activity

vendoring

Browse Source
This commit is contained in:
SheetJS 2024-09-23 11:39:01 -04:00
parent 3553757e8d
commit 3d661faddb
7 changed files with 157 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docz/docs/02-getting-started/01-installation/01-standalone.mdx
View File

@ -121,8 +121,8 @@ importScripts("https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.mi
:::danger VSCode Telemetry and Data Exfiltration
The official Microsoft builds of Visual Studio Code embed telemetry and send
information to external servers.
The official Microsoft builds of Visual Studio Code ("VSCode") embed telemetry
and send information to external servers.
**[VSCodium](https://vscodium.com/) is a telemetry-free fork of VSCode.**

26
docz/docs/02-getting-started/01-installation/02-frameworks.md
View File

@ -174,10 +174,30 @@ yarn remove xlsx`}
<ol start="1"><li><p>Download the tarball (<code parentName="pre">xlsx-{current}.tgz</code>) for the desired version. The current
version is available at <a href={"https://cdn.sheetjs.com/xlsx-" + current + "/xlsx-" + current + ".tgz"}>{"https://cdn.sheetjs.com/xlsx-" + current + "/xlsx-" + current + ".tgz"}</a></p></li></ol>
2) Create a `vendor` subfolder at the root of your project and move the tarball
to that folder. Add it to your project repository.
<CodeBlock language="bash">{`\
curl -o https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>
3) Install the tarball using a package manager:
2) Create a `vendor` subfolder at the root of your project:
```bash
mkdir -p vendor
```
3) Move the tarball from step (1) to the `vendor` folder:
<CodeBlock language="bash">{`\
mv xlsx-${current}.tgz vendor`}
</CodeBlock>
4) If the project is managed with a version control system, add the tarball to
the source repository. The Git VCS supports the `add` subcommand:
<CodeBlock language="bash">{`\
git add vendor/xlsx-${current}.tgz`}
</CodeBlock>
5) Install the tarball using a package manager:
<Tabs groupId="pm">
<TabItem value="npm" label="npm">

91
docz/docs/02-getting-started/01-installation/03-nodejs.md
View File

@ -161,12 +161,33 @@ yarn remove xlsx`}
</TabItem>
</Tabs>
<ol start="1"><li><p>Download the tarball (<code parentName="pre">xlsx-{current}.tgz</code>) for the desired version. The current version is available at <a href={"https://cdn.sheetjs.com/xlsx-" + current + "/xlsx-" + current + ".tgz"}>{"https://cdn.sheetjs.com/xlsx-" + current + "/xlsx-" + current + ".tgz"}</a></p></li></ol>
<ol start="1"><li><p>Download the tarball (<code parentName="pre">xlsx-{current}.tgz</code>) for the desired version. The current
version is available at <a href={"https://cdn.sheetjs.com/xlsx-" + current + "/xlsx-" + current + ".tgz"}>{"https://cdn.sheetjs.com/xlsx-" + current + "/xlsx-" + current + ".tgz"}</a></p></li></ol>
2) Create a `vendor` subfolder at the root of your project and move the tarball
to that folder. Add it to your project repository.
<CodeBlock language="bash">{`\
curl -o https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>
3) Install the tarball using a package manager:
2) Create a `vendor` subfolder at the root of your project:
```bash
mkdir -p vendor
```
3) Move the tarball from step (1) to the `vendor` folder:
<CodeBlock language="bash">{`\
mv xlsx-${current}.tgz vendor`}
</CodeBlock>
4) If the project is managed with a version control system, add the tarball to
the source repository. The Git VCS supports the `add` subcommand:
<CodeBlock language="bash">{`\
git add vendor/xlsx-${current}.tgz`}
</CodeBlock>
5) Install the tarball using a package manager:
<Tabs groupId="pm">
<TabItem value="npm" label="npm">
@ -230,6 +251,66 @@ The package also ships with `xlsx.mjs`, a script compatible with the ECMAScript
module system. When using the ESM build in NodeJS, some dependencies must be
loaded manually.
:::danger ECMAScript Module Limitations
The original ECMAScript module specification only supported top-level imports:
```js
import { Readable } from 'stream';
```
If a module is unavailable, there is no way for scripts to gracefully fail or
ignore the error. This presents an insurmountable challenge for libraries.
To contrast, the SheetJS CommonJS modules gracefully handle missing dependencies
since `require` failures are errors that the library can catch and handle.
---
Patches to the specification added two different solutions to the problem:
- "dynamic imports" will throw errors that can be handled by libraries. Dynamic
imports will taint APIs that do not use Promise-based methods.
```js
/* Readable will be undefined if stream cannot be imported */
const Readable = await (async() => {
try {
return (await import("stream"))?.Readable;
} catch(e) { /* silently ignore error */ }
})();
```
- "import maps" control module resolution, allowing library users to manually
shunt unsupported modules.
**These patches were released after browsers adopted ESM!** A number of browsers
and other platforms support top-level imports but do not support the patches.
---
For the ESM build, there were four unpalatable options:
A) Generate a module script for browsers, a module script for ViteJS, a module
script for [Deno](/docs/getting-started/installation/deno), and a module script
for NodeJS and [BunJS](/docs/getting-started/installation/bun).
B) Remove all optional features, including support for non-English legacy files.
C) Add all optional features, effectively making the features mandatory.
D) Introduce special methods for optional dependency injection.
The SheetJS team chose option (D). NodeJS native modules are still automatically
loaded in the CommonJS build, but NodeJS ESM scripts must now load and pass the
dependencies to the library using special methods.
---
**It is strongly recommended to use CommonJS in NodeJS scripts!**
:::
#### Filesystem Operations
The `set_fs` method accepts a `fs` instance for reading and writing files using
@ -285,6 +366,8 @@ import * as fs from 'fs'; // this import will fail
set_fs(fs);
```
**This is a design flaw in NextJS!**
:::
For server-side file processing, `fs` should be loaded with a dynamic import

3
docz/docs/02-getting-started/01-installation/07-bun.md
View File

@ -122,6 +122,7 @@ This demo was last tested in the following deployments:
| Architecture | BunJS | Date |
|:-------------|:---------|:-----------|
| `darwin-x64` | `1.1.4` | 2024-04-19 |
| `darwin-arm` | `1.1.10` | 2024-09-22 |
| `win10-x64` | `1.1.4` | 2024-04-19 |
| `win11-x64` | `1.1.22` | 2024-08-11 |
| `linux-x64` | `1.1.4` | 2024-04-25 |
@ -136,7 +137,7 @@ cd sheetjs-bun-dle
echo "{}" > package.json
```
:::caution pass
:::caution PowerShell Encoding Errors
The PowerShell file redirect will use the `UTF-16 LE` encoding. Bun does not
support the encoding and will fail to install the package:

2
docz/docs/03-demos/12-static/12-astro.md
View File

@ -110,7 +110,7 @@ export default defineConfig({
#### Types
For VSCode and VSCodium integration, types can be specified in `src/env.d.ts`.
For VSCodium integration, types can be specified in `src/env.d.ts`.
This data loader returns Base64 strings:

2
docz/docs/07-csf/07-features/12-props.md
View File

@ -130,7 +130,7 @@ wb.Custprops["Custom Quip"] = "Get Sheet Done";
## Export Override
The SheetJS `write` and `writeFile` methods[^2] accept options. The `Props`
The SheetJS `write` and `writeFile` methods[^1] accept options. The `Props`
option instructs the writer to override properties from the workbook object.
In the following example, the workbook object sets the "Title" and "Keywords"

56
docz/docs/09-miscellany/05-contributing.md
View File

@ -529,7 +529,7 @@ Date: Fri Jul 12 11:47:14 2024 -0400
git checkout 8a7cfd47bde8258c0d91df6a737bf0136699cdf8
```
7) Run the full build sequence
7) Run the full build sequence:
```bash
make clean; make
@ -538,9 +538,10 @@ make
make dist
```
8) To verify that the files are intact, use `md5sum` (`md5` on MacOS).
8) Verify the scripts by computing the MD5 checksum.
The local checksum for the browser script can be computed with:
The checksum for the generated `xlsx.full.min.js` script can be computed using
the `md5` command on macOS or the `md5sum` command on WSL and Linux.
<Tabs groupId="os">
<TabItem value="wsl" label="Windows WSL">
@ -567,13 +568,25 @@ md5sum dist/xlsx.full.min.js
</Tabs>
The checksum for the CDN version can be computed with:
The checksum for the equivalent script on the SheetJS CDN can be computed with:
<Tabs groupId="os">
<TabItem value="wsl" label="Windows WSL">
```bash
curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5sum -
```
The following output was captured in `win11-arm` for SheetJS version `0.20.3`:
>
```bash
$ md5sum dist/xlsx.full.min.js
# highlight-next-line
6b3130af1ceadf07caa0ec08af7addff dist/xlsx.full.min.js
$ curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5sum -
# highlight-next-line
6b3130af1ceadf07caa0ec08af7addff -
```
</TabItem>
@ -583,17 +596,7 @@ curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5s
curl -k -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5
```
</TabItem>
<TabItem value="l" label="Linux">
```bash
curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5sum -
```
</TabItem>
</Tabs>
When the demo was last tested on macOS, against version `0.20.3`:
The following output was captured in `darwin-arm` for SheetJS version `0.20.3`:
>
```bash
@ -605,6 +608,29 @@ $ curl -k -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js |
6b3130af1ceadf07caa0ec08af7addff
```
</TabItem>
<TabItem value="l" label="Linux">
```bash
curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5sum -
```
The following output was captured in `linux-arm` for SheetJS version `0.20.3`:
>
```bash
$ md5sum dist/xlsx.full.min.js
# highlight-next-line
6b3130af1ceadf07caa0ec08af7addff dist/xlsx.full.min.js
$ curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5sum -
# highlight-next-line
6b3130af1ceadf07caa0ec08af7addff -
```
</TabItem>
</Tabs>
The two hashes should match.
9) Return to the `HEAD` commit: