docs.sheetjs.com/docz/docs/02-getting-started/01-installation/07-bun.md

259 lines
6.5 KiB
Markdown
Raw Normal View History

2022-07-09 23:59:44 +00:00
---
2023-10-16 09:12:56 +00:00
title: Bun
2022-08-24 23:48:22 +00:00
pagination_prev: getting-started/index
2023-07-26 20:18:07 +00:00
pagination_next: getting-started/examples/index
2022-07-09 23:59:44 +00:00
sidebar_position: 7
sidebar_custom_props:
2023-09-17 04:57:06 +00:00
summary: Load NodeJS-style modules using CommonJS or ESM
2022-07-09 23:59:44 +00:00
---
import current from '/version.js';
2024-03-12 06:47:52 +00:00
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
2023-09-17 04:57:06 +00:00
import CodeBlock from '@theme/CodeBlock';
2022-07-09 23:59:44 +00:00
Package tarballs are available on https://cdn.sheetjs.com.
2022-07-09 23:59:44 +00:00
<p><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 version {current}</p>
2022-07-09 23:59:44 +00:00
2023-03-28 04:57:47 +00:00
:::caution Bun support is considered experimental.
Great open source software grows with user tests and reports. Any issues should
be reported to the Bun project for further diagnosis.
:::
2023-09-17 04:57:06 +00:00
## Installation
2024-03-12 06:47:52 +00:00
Tarballs can be directly installed with `bun install`:
2023-09-17 04:57:06 +00:00
<CodeBlock language="bash">{`\
2024-03-20 07:05:29 +00:00
bun rm xlsx
2023-09-17 04:57:06 +00:00
bun install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>
2023-06-25 09:36:58 +00:00
:::tip pass
2023-04-27 09:12:19 +00:00
[Watch the repo](https://git.sheetjs.com/SheetJS/sheetjs) or subscribe to the
[RSS feed](https://git.sheetjs.com/sheetjs/sheetjs/tags.rss) to be notified when
new versions are released!
:::
2024-03-12 06:47:52 +00:00
### Vendoring
2023-09-17 04:57:06 +00:00
2024-03-12 06:47:52 +00:00
For general stability, "vendoring" modules is the recommended approach:
2023-09-17 04:57:06 +00:00
2024-03-20 07:05:29 +00:00
0) Remove any existing dependency on a project named `xlsx`:
```bash
bun rm 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>
2024-03-12 06:47:52 +00:00
2) Create a `vendor` subfolder at the root of your project and move the tarball
to that folder. Add it to your project repository.
3) Install the tarball:
<CodeBlock language="bash">{`\
bun install file:vendor/xlsx-${current}.tgz`}
</CodeBlock>
The package will be installed and accessible as `xlsx`.
2022-07-09 23:59:44 +00:00
2023-09-17 04:57:06 +00:00
## Usage
2022-07-09 23:59:44 +00:00
2024-03-12 06:47:52 +00:00
The package supports CommonJS `require` and ESM `import` module systems.
2022-07-09 23:59:44 +00:00
2023-09-17 04:57:06 +00:00
:::info pass
2023-09-24 03:59:48 +00:00
**It is strongly recommended to use CommonJS in Bun.**
2023-09-17 04:57:06 +00:00
:::
2024-03-12 06:47:52 +00:00
### CommonJS `require`
2023-09-17 04:57:06 +00:00
By default, the module supports `require` and it will automatically add support
2024-07-18 22:19:02 +00:00
for encodings, streams and file system access:
2023-09-17 04:57:06 +00:00
```js
const { readFile } = require("xlsx");
const wb = readFile("pres.numbers"); // works!
```
2024-03-12 06:47:52 +00:00
:::caution pass
In the BunJS REPL, `require` incorrectly loads the ESM build.
:::
### ESM `import`
2023-09-17 04:57:06 +00:00
When importing the library using ESM `import` statements, the native NodeJS
modules are not loaded. They must be added manually:
```js
import * as XLSX from 'xlsx';
/* load 'fs' for readFile and writeFile support */
import * as fs from 'fs';
XLSX.set_fs(fs);
/* load 'stream' for stream support */
import { Readable } from 'stream';
XLSX.stream.set_readable(Readable);
2022-07-09 23:59:44 +00:00
/* load the codepage support library for extended support with older formats */
2023-09-17 04:57:06 +00:00
import * as cpexcel from 'xlsx/dist/cpexcel.full.mjs';
XLSX.set_cptable(cpexcel);
2022-07-09 23:59:44 +00:00
```
2023-09-17 04:57:06 +00:00
2023-10-22 05:40:02 +00:00
## Bundling
For server-side scripts, `bun build` can pre-optimize dependencies. The Bun
builder requires a proper `package.json` that includes the SheetJS dependency.
2023-11-04 05:05:26 +00:00
:::note Tested Deployments
2023-10-22 05:40:02 +00:00
2024-04-11 17:44:06 +00:00
This demo was last tested in the following deployments:
2024-08-12 05:40:33 +00:00
| Architecture | BunJS | Date |
|:-------------|:---------|:-----------|
| `darwin-x64` | `1.1.4` | 2024-04-19 |
| `win10-x64` | `1.1.4` | 2024-04-19 |
| `win11-x64` | `1.1.22` | 2024-08-11 |
| `linux-x64` | `1.1.4` | 2024-04-25 |
2023-10-22 05:40:02 +00:00
:::
0) Create a new project:
```bash
mkdir sheetjs-bun-dle
cd sheetjs-bun-dle
2024-03-12 06:47:52 +00:00
echo "{}" > package.json
2023-10-22 05:40:02 +00:00
```
:::caution pass
2024-08-12 05:40:33 +00:00
The PowerShell file redirect will use the `UTF-16 LE` encoding. Bun does not
support the encoding and will fail to install the package:
```
bun add v1.1.22-canary.96 (df33f2b2)
1 | <20><>{}
^
error: Unexpected <20><>
```
The file must be resaved in UTF8 (without BOM) or ASCII.
0) Open `package.json` in VSCodium.
The current encoding is displayed in the lower-right corner:
![VSCodium status bar](pathname:///files/encodium.png)
1) Click the displayed encoding.
2) In the "Select Action" popup, select "Save with Encoding"
3) In the new list, select `UTF-8 utf8`:
![VSCodium encoding](pathname:///files/vscutf8.png)
VSCodium will automatically re-save the file.
:::
1) Install the SheetJS package tarball:
2023-10-22 05:40:02 +00:00
<CodeBlock language="bash">{`\
bun install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>
2024-03-12 06:47:52 +00:00
2) Save the following script to `SheetJSBun.js`:
2023-10-22 05:40:02 +00:00
2024-03-12 06:47:52 +00:00
```js title="SheetJSBun.js"
2023-10-22 05:40:02 +00:00
// highlight-next-line
import * as XLSX from 'xlsx';
// highlight-next-line
import * as fs from 'fs';
// highlight-next-line
XLSX.set_fs(fs);
/* fetch JSON data and parse */
2024-04-26 04:16:13 +00:00
const url = "https://docs.sheetjs.com/executive.json";
2023-10-22 05:40:02 +00:00
const raw_data = await (await fetch(url)).json();
/* filter for the Presidents */
2023-11-04 05:05:26 +00:00
const prez = raw_data.filter(row => row.terms.some(term => term.type === "prez"));
/* sort by first presidential term */
prez.forEach(row => row.start = row.terms.find(term => term.type === "prez").start);
prez.sort((l,r) => l.start.localeCompare(r.start));
2023-10-22 05:40:02 +00:00
/* flatten objects */
2023-11-04 05:05:26 +00:00
const rows = prez.map(row => ({
2023-10-22 05:40:02 +00:00
name: row.name.first + " " + row.name.last,
birthday: row.bio.birthday
}));
/* generate worksheet and workbook */
const worksheet = XLSX.utils.json_to_sheet(rows);
const 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 */
const max_width = rows.reduce((w, r) => Math.max(w, r.name.length), 10);
worksheet["!cols"] = [ { wch: max_width } ];
/* create an XLSX file and try to save to Presidents.xlsx */
XLSX.writeFile(workbook, "Presidents.xlsx");
```
3) Bundle the script with `bun build`:
```bash
2024-03-12 06:47:52 +00:00
bun build --target=bun SheetJSBun.js --outfile=app.js
2023-10-22 05:40:02 +00:00
```
This procedure will generate `app.js`.
2024-03-12 06:47:52 +00:00
4) Remove the module artifacts and original script:
2023-10-22 05:40:02 +00:00
```bash
2024-03-12 06:47:52 +00:00
rm package.json bun.lockb SheetJSBun.js
2023-10-22 05:40:02 +00:00
rm -rf ./node_modules
```
:::note pass
PowerShell does not support `rm -rf`. Instead, each file must be removed:
```powershell title="Windows Powershell commands"
rm package.json
rm bun.lockb
rm SheetJSBun.js
rm .\\node_modules -r -fo
```
:::
2024-03-12 06:47:52 +00:00
At this point, `app.js` will be the only file in the project folder.
2023-10-22 05:40:02 +00:00
5) Run the script:
```bash
bun app.js
```
If the script succeeded, the file `Presidents.xlsx` will be created. That file
can be opened in a spreadsheet editor.