docs.sheetjs.com/docz/docs/02-getting-started/01-installation/07-bun.md
2023-10-22 03:32:00 -04:00

4.6 KiB

title pagination_prev pagination_next sidebar_position sidebar_custom_props
Bun getting-started/index getting-started/examples/index 7
summary
Load NodeJS-style modules using CommonJS or ESM

import current from '/version.js'; import CodeBlock from '@theme/CodeBlock';

Tarballs are available on https://cdn.sheetjs.com.

https://cdn.sheetjs.com/xlsx-{current}/xlsx-{current}.tgz is the URL for version {current}

:::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.

:::

Installation

Tarballs can be directly installed with bun install1:

{\ bun install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz}

:::tip pass

Watch the repo or subscribe to the RSS feed to be notified when new versions are released!

:::

:::warning pass

At the time of writing bun install does not support vendored tarballs2.

:::

Usage

Bun supports both "CommonJS" and "ESM" modules.

:::info pass

It is strongly recommended to use CommonJS in Bun.

:::

CommonJS require

By default, the module supports require and it will automatically add support for streams and file system access:

const { readFile } = require("xlsx");
const wb = readFile("pres.numbers"); // works!

ESM import

When importing the library using ESM import statements, the native NodeJS modules are not loaded. They must be added manually:

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

/* load the codepage support library for extended support with older formats  */
import * as cpexcel from 'xlsx/dist/cpexcel.full.mjs';
XLSX.set_cptable(cpexcel);

Bundling

For server-side scripts, bun build can pre-optimize dependencies. The Bun builder requires a proper package.json that includes the SheetJS dependency.

:::note

This example was last tested on 2023 October 21 against BunJS 1.0.6.

:::

  1. Create a new project:
mkdir sheetjs-bun-dle
cd sheetjs-bun-dle
echo "{}" >> package.json
  1. Install the library:

{\ bun install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz}

  1. Save the following script to bun.js:
// 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 */
const url = "https://sheetjs.com/data/executive.json";
const raw_data = await (await fetch(url)).json();

/* filter for the Presidents */
const prez = raw_data.filter((row) => row.terms.some((term) => term.type === "prez"));

/* flatten objects */
const rows = prez.map((row) => ({
  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");
  1. Bundle the script with bun build:
bun build --target=bun bun.js --outfile=app.js

This procedure will generate app.js.

  1. Remove the node_modules directory and package.json file:
rm package.json
rm -rf ./node_modules
  1. Run the script:
bun app.js

If the script succeeded, the file Presidents.xlsx will be created. That file can be opened in a spreadsheet editor.


  1. Bun releases before the official 1.0.0 release did not support tarball dependencies. If a pre-1.0.0 release must be used, the ES Module script can be vendored or the NodeJS module can be installed with a NodeJS-compatible package manager. ↩︎

  2. See the relevant issue in the Bun issue tracker ↩︎