Command-Line Tools
With the availability of JS engines and the success of server-side platforms, it is possible to build standalone command-line tools from JavaScript code.
SheetJS is a JavaScript library for reading and writing data from spreadsheets.
This demo covers a number of strategies for building standalone spreadsheet processors. The ultimate goal is to use SheetJS libraries to generate CSV output from arbitrary spreadsheet files. The generated command-line tool will accept an argument, parse the specified workbook, and print CSV rows to the terminal.
Sample terminal session
$ xlsx-cli.exe pres.numbers
Name,Index
Bill Clinton,42
GeorgeW Bush,43
Barack Obama,44
Donald Trump,45
Joseph Biden,46
Demos for common standalone CLI tools are included in separate pages:
- NodeJS SEA - Single Executable Applications
- Deno Compiler - Deno Standalone Binaries
The xlsx-cli
NodeJS script is available
as a package on the SheetJS CDN. It is an easy-to-use command-line tool for
translating files between supported spreadsheet file formats.
For most common deployment scenarios, it is possible to install a server-side platform such as NodeJS.
It is strongly recommended to use a dedicated platform when possible.
The standalone programs generated in this demo are useful when a dedicated server-side scripting platform cannot be installed on the target computer.
NodeJS
There are a few popular tools for compiling NodeJS scripts to CLI programs.
The demo script presents a friendly command line interface including flags:
$ ./xlsx-cli -h
Usage: xlsx-cli [options] <file> [sheetname]
Options:
-V, --version output the version number
-f, --file <file> use specified workbook
-s, --sheet <sheet> print specified sheet (default first sheet)
...
This demo was tested in the following deployments:
- Nexe
- pkg
- boxednode
Architecture | Version | NodeJS | Source | Date |
---|---|---|---|---|
darwin-x64 | 4.0.0-rc.4 | 14.15.3 | Pre-built | 2024-03-15 |
darwin-arm | 4.0.0-rc.2 | 18.18.0 | Compiled | 2023-12-01 |
win10-x64 | 4.0.0-rc.4 | 14.15.3 | Pre-built | 2024-03-04 |
win11-arm | 4.0.0-rc.2 | 20.10.0 | Compiled | 2023-12-01 |
linux-x64 | 4.0.0-rc.4 | 14.15.3 | Pre-built | 2024-03-21 |
linux-arm | 4.0.0-rc.2 | 20.10.0 | Compiled | 2023-12-01 |
Architecture | Version | NodeJS | Date |
---|---|---|---|
darwin-x64 | 5.8.1 | 18.5.0 | 2024-03-15 |
darwin-arm | 5.8.1 | 18.5.0 | 2023-12-01 |
win10-x64 | 5.8.1 | 18.5.0 | 2024-03-24 |
win11-arm | 5.8.1 | 18.5.0 | 2023-12-01 |
linux-x64 | 5.8.1 | 18.5.0 | 2024-03-21 |
linux-arm | 5.8.1 | 18.5.0 | 2023-12-01 |
Architecture | Version | NodeJS | Date |
---|---|---|---|
darwin-x64 | 2.4.0 | 21.7.1 | 2024-03-15 |
darwin-arm | 2.3.0 | 21.3.0 | 2023-12-01 |
win10-x64 | 2.4.0 | 16.20.2 | 2024-03-24 |
linux-x64 | 2.4.0 | 21.7.1 | 2024-03-21 |
linux-arm | 2.3.0 | 21.3.0 | 2023-12-01 |
0) Download the test file https://sheetjs.com/pres.numbers:
curl -o pres.numbers https://sheetjs.com/pres.numbers
1) Download xlsx-cli.js
curl -o xlsx-cli.js https://docs.sheetjs.com/cli/xlsx-cli.js
2) Install the dependencies:
- npm
- pnpm
- Yarn
npm i --save https://cdn.sheetjs.com/xlsx-0.20.1/xlsx-0.20.1.tgz exit-on-epipe commander@2
pnpm install --save https://cdn.sheetjs.com/xlsx-0.20.1/xlsx-0.20.1.tgz exit-on-epipe commander@2
yarn add https://cdn.sheetjs.com/xlsx-0.20.1/xlsx-0.20.1.tgz exit-on-epipe commander@2
3) Follow tooling steps:
- Nexe
- pkg
- boxednode
Run nexe
and manually specify NodeJS version 14.15.3
npx nexe -t 14.15.3 xlsx-cli.js
This generates xlsx-cli
or xlsx-cli.exe
depending on platform.
When the demo was tested on ARM targets, the Nexe pre-built packages were missing. The package must be built from source:
npx nexe xlsx-cli.js --build --python=$(which python3) --make="-j8"
On Windows ARM, the target windows-arm64-20.10.0
must be specified:
npx nexe xlsx-cli.js --build --make="-j8" --target=windows-arm64-20.10.0
The Windows build may fail with a vcbuild.bat
error:
Error: vcbuild.bat nosign release arm64 exited with code: 1
Pass the -v
flag for more details. In the most recent test, the error stemmed
from a Python version mismatch:
Node.js configure: found Python 2.7.18
Please use python3.11 or python3.10 or python3.9 or python3.8 or python3.7 or python3.6
The resolved version of Python can be found with
where python
In the most recent test, a Python 2 version appeared first. This was fixed by
finding the Python 3 location and prepending it to PATH
:
set PATH="C:\correct\path\to\python\three";%PATH%
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!
The local NodeJS version must be rolled back to version 18.
If n
is installed:
sudo n 18
If nvm
was used to install NodeJS:
nvm install 18
nvm use 18
Run pkg
:
npx pkg xlsx-cli.js
This generates xlsx-cli-linux
, xlsx-cli-macos
, and xlsx-cli-win.exe
.
Run boxednode
:
- Linux/MacOS
- Windows
npx [email protected] -s xlsx-cli.js -t xlsx-cli
npx [email protected] -s xlsx-cli.js -t xlsx-cli.exe -n 16.20.2
The Windows 10 build requires Visual Studio with "Desktop development with C++" workload, Python 3.11, and NASM1.
The build command must be run in "x64 Native Tools Command Prompt"
When the demo was last tested, the build failed:
Not an executable Python program
Could not find Python.
By default, Windows aliases python
to a Microsoft Store installer. If the
official installer was used, the alias should be disabled manually:
1) Open Start menu and type "app alias". Click "Manage app execution aliases".
2) Disable the App Installer for all items with python
in the name.
Using Python 3.12, the build fails with an error:
Please use python3.11 or python3.10 or python3.9 or python3.8 or python3.7 or python3.6.
In the most recent test, Python 3.11.8 was installed from the official site.
When the demo was last tested on Windows, the build failed:
error MSB8020: The build tools for Visual Studio 2019 (Platform Toolset = 'v142') cannot be found. To build using the v142 build tools, please install Visual Studio 2019 build tools.
This error was fixed by installing the v142
build tools through the Visual
Studio installer.
In the most recent Windows test against NodeJS 20.8.0
, the build failed due
to an issue in the OpenSSL dependency:
...\node-v20.8.0\deps\openssl\openssl\crypto\cversion.c(75,33): error C2153: integer literals must have at least one digit [...\node-v20.8.0\deps\openssl\openssl.vcxproj]
SheetJS libraries are compatible with NodeJS versions dating back to v0.8
. The
workaround is to select NodeJS v16.20.2
using the -n
flag. This version was
was chosen since NodeJS v18
upgraded the OpenSSL dependency.
4) Run the generated program, passing pres.numbers
as the argument. For
example, nexe
generates xlsx-cli
in macOS so the command is:
./xlsx-cli pres.numbers
nexe
generates xlsx-cli.exe
in Windows, so the command is:
.\xlsx-cli.exe pres.numbers
V8
The V8 demo covers standalone programs that embed the V8 engine. This demo uses the Rust integration to generate a command line tool.
This demo was last tested in the following deployments:
Architecture | V8 Version | Crate | Date |
---|---|---|---|
darwin-x64 | 12.3.219.9 | 0.88.0 | 2024-03-15 |
darwin-arm | 11.8.172.13 | 0.79.2 | 2023-10-18 |
win10-x64 | 12.3.219.9 | 0.88.0 | 2024-03-24 |
win11-x64 | 11.8.172.13 | 0.79.2 | 2023-10-14 |
linux-x64 | 12.3.219.9 | 0.88.0 | 2024-03-18 |
linux-arm | 12.0.267.8 | 0.82.0 | 2023-12-01 |
0) Make a new folder for the project:
mkdir sheetjs2csv
cd sheetjs2csv
1) Download the following scripts:
curl -o Cargo.toml https://docs.sheetjs.com/cli/Cargo.toml
curl -o snapshot.rs https://docs.sheetjs.com/cli/snapshot.rs
curl -o sheet2csv.rs https://docs.sheetjs.com/cli/sheet2csv.rs
2) Download the SheetJS Standalone script and move to the project directory:
curl -o xlsx.full.min.js https://cdn.sheetjs.com/xlsx-0.20.1/package/dist/xlsx.full.min.js
3) Build the V8 snapshot:
cargo build --bin snapshot
cargo run --bin snapshot
With some versions of the v8
crate, the Linux AArch64 build failed with an error:
error[E0080]: evaluation of constant value failed
|
1715 | assert!(size_of::<TypeId>() == size_of::<u64>());
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the evaluated program panicked at 'assertion failed: size_of::<TypeId>() == size_of::<u64>()'
Versions 0.75.1
and 0.82.0
are known to work.
4) Build sheet2csv
(sheet2csv.exe
in Windows):
cargo build --release --bin sheet2csv
5) Download the test file https://sheetjs.com/pres.numbers:
curl -o pres.numbers https://sheetjs.com/pres.numbers
6) Test the application:
- Linux/MacOS
- Windows
mv target/release/sheet2csv .
./sheet2csv pres.numbers
mv target/release/sheet2csv.exe .
.\sheet2csv.exe pres.numbers
Deno
The exposition has been moved to a separate page.
Dedicated Engines
The following demos for JS engines produce standalone programs:
- Downloads can be found at the main NASM project website↩