Skip to main content

Packing Sheets with pkg

pkg1 is a tool for generating command-line tools that embed scripts.

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

This demo uses pkg and SheetJS to create a standalone CLI tool for parsing spreadsheets and converting to other formats.

With the official release of NodeJS SEA, Vercel opted to deprecate pkg. It is still useful for deploying apps embedding NodeJS v18 or earlier since those versions do not support NodeJS SEA.

Tested Deployments

This demo was tested in the following deployments:

ArchitectureVersionNodeJSDate
darwin-x645.8.118.5.02024-05-28
darwin-arm5.8.118.5.02024-05-25
win10-x645.8.118.5.02024-04-18
win11-arm5.8.118.5.02024-10-25
linux-x645.8.118.5.02024-03-21
linux-arm5.8.118.5.02024-05-26

pkg on Windows on ARM uses the X64 compatibility layer. It does not generate a native ARM64 binary!

Integration Details​

The SheetJS NodeJS module can be required from scripts. pkg will automatically handle packaging.

Script Requirements​

Scripts that exclusively use SheetJS libraries and NodeJS built-in modules can be bundled using pkg.

The demo script xlsx-cli.js runs in NodeJS. It is a simple command-line tool for reading and writing spreadsheets.

Limitations​

When this demo was last tested, pkg failed with an error referencing node20:

> Targets not specified. Assuming:
  node20-linux-arm64, node20-macos-arm64, node20-win-arm64
> Error! No available node version satisfies 'node20'

pkg does not support NodeJS 20 or 22!

The local NodeJS version must be rolled back to version 18.

If nvm or nvm-windows was used to install NodeJS:

nvm install 18
nvm use 18

Otherwise, on macOS and Linux, n can manage the global installation:

sudo npm i -g n
sudo n 18

On Windows, it is recommended to use a prebuilt installer2

Complete Example​

  1. Downgrade NodeJS to major version 18 or earlier.

  2. Download the test file https://docs.sheetjs.com/pres.numbers:

curl -o pres.numbers https://docs.sheetjs.com/pres.numbers
  1. Download xlsx-cli.js
curl -o xlsx-cli.js https://docs.sheetjs.com/cli/xlsx-cli.js
  1. Install the dependencies:
yarn add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz exit-on-epipe commander@2
  1. Create the standalone program:
npx pkg xlsx-cli.js

This generates xlsx-cli-linux, xlsx-cli-macos, and xlsx-cli-win.exe .

  1. Run the generated program, passing pres.numbers as the argument:
./xlsx-cli-linux pres.numbers

Footnotes​

  1. The project does not have a website. The source repository is publicly available. ↩

  2. The NodeJS website hosts prebuilt installers. ↩