Skip to main content

Bundling Sheets with ESBuild

ESBuild is a fast module bundler for JavaScript. It combines scripts and libraries into simple scripts for browsers and NodeJS.

SheetJS is a JavaScript library for reading and writing data from spreadsheets.

This demo uses ESBuild and SheetJS to export data. We'll explore two workflows:

  • "Browser" explores how to import SheetJS libraries in a script and bundle with ESBuild for browser use.

  • "NodeJS" explores how to import SheetJS libraries in a script and bundle with ESBuild for NodeJS use.

The ESBuild section of the Content demo covers loaders. They are ideal for static sites pulling data from sheets at build time.

This demo focuses on integration details with the ESBuild bundler.

The demos follow the "Export Tutorial", which covers SheetJS library usage in more detail.

Tested Deployments

This demo was tested in the following environments:

ESBuildDate
0.21.42024-06-07
0.20.22024-06-07
0.19.122024-06-07
0.18.202024-06-07
0.17.192024-06-07
0.16.172024-06-07
0.15.182024-06-07
0.14.542024-06-07
0.13.152024-06-07
0.12.292024-06-07
0.11.232024-06-07
0.10.22024-06-07
0.9.72024-06-07

Integration Details

The "Frameworks" section covers installation with Yarn and other package managers.

Browser

ESBuild will bundle the SheetJS ECMAScript Module build:

import { read, utils, writeFileXLSX } from 'xlsx';

The xlsx.mjs source file uses a subset of ES6 that esbuild understands and is able to transpile for older browsers.

Assuming the primary source file is in.js, the following command will bundle the script and generate out.js:

npx -y [email protected] in.js --bundle --outfile=out.js

Browser Demo

  1. Prepare a blank project:
mkdir sheetjs-esbrowser
cd sheetjs-esbrowser
npm init -y
  1. Install the tarball using a package manager:
yarn add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz
  1. Download esbrowser.js and move to the project folder:
curl -LO https://docs.sheetjs.com/esbuild/esbrowser.js
  1. Create a small HTML page that loads the script. Save to index.html:
index.html
<body><script src="esb.browser.js"></script></body>
  1. Create bundle:
npx -y [email protected] esbrowser.js --bundle --outfile=esb.browser.js
  1. Start a local HTTP server:
npx http-server .

Access the displayed URL (typically http://localhost:8080) with a web browser. It should attempt to download Presidents.xlsx

NodeJS

ESBuild will bundle the SheetJS ECMAScript Module build:

import { read, utils, write } from 'xlsx';

To read and write files on the local filesystem using the SheetJS readFile and writeFile methods1, the fs module must be manually added:

import { set_fs, readFile } from 'xlsx';
import * as fs from 'fs';
set_fs(fs);

/* read pres.numbers in the same directory as the script */
const wb = readFile("pres.numbers");

Assuming the primary source file is in.js, the following command will bundle the script for NodeJS and generate out.js:

npx -y [email protected] in.js --bundle --platform=node --outfile=out.js

NodeJS Demo

This demo script uses fetch and requires Node 18+.

  1. Prepare a blank project:
mkdir sheetjs-esbnode
cd sheetjs-esbnode
npm init -y
  1. Install the tarball using a package manager:
yarn add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz
  1. Download esbnode.js and move to the project folder:
curl -LO https://docs.sheetjs.com/esbuild/esbnode.js
  1. Create bundle:
npx -y [email protected] esbnode.js --bundle --platform=node --outfile=esb.node.js
  1. Run the bundle:
node esb.node.js

The process will generate Presidents.xlsx in the project directory. Open the file in a spreadsheet editor.

Footnotes

  1. The SheetJS readFile and writeFile methods use the NodeJS fs module when available. It is not automatically loaded in the ECMAScript Module builds.