Skip to main content

Contributing

Due to the precarious nature of the Open Specifications Promise, it is very important to ensure code is cleanroom.

The Contribution Notes should be perused before contributing code.

File organization (click to show)

Folders:

foldercontents
binserver-side bin scripts (xlsx.njs)
bitsraw source files that make up the final script
distdist files for web browsers and nonstandard JS environments
miscmiscellaneous supporting scripts
modulesTypeScript source files that generate some of the bits
packagesSupport libraries and tools
test_filestest files (pulled from the test artifacts distribution)
testsbrowser tests (run make ctest to rebuild)
typesTypeScript definitions and tests

After cloning the repo, running make help will display a list of commands.

Setup​

These instructions will cover system configuration, cloning the source repo, building, reproducing official releases, and running NodeJS and browser tests.

Tested Deployments

These instructions were tested on the following platforms:

PlatformArchitectureTest Date
Linux (Steam Deck Holo x64)linux-x642025-01-10
Linux (Debian Linux AArch64)linux-arm2025-01-14
MacOS 15.3 (x64)darwin-x642025-03-31
MacOS 15.2 (ARM64)darwin-arm2025-03-07
Windows 10 (x64) + WSL Ubuntuwin10-x642024-07-12
Windows 11 (x64) + WSL Ubuntuwin11-x642025-01-14
Windows 11 (ARM) + WSL Ubuntuwin11-arm2025-02-23

With some additional dependencies, the unminified scripts are reproducible and tests will pass in Windows XP with NodeJS 5.10.0.

Install dependencies​

OS-Specific Setup​

A) Open a terminal window and run git:

git --version

If Xcode or the command-line tools are not installed, you will be asked to install. Click "Install" and run through the steps.

B) Open a terminal window and install the Homebrew package manager:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the on-screen instructions.

After the installation finishes, add Homebrew to your PATH. The instructions are displayed in the Next steps section:

: # zsh
echo >> $HOME/.zprofile
echo 'if [ -e "/opt/homebrew/bin/brew" ]; then eval "$(/opt/homebrew/bin/brew shellenv)"; fi' >> $HOME/.zprofile
echo 'if [ -e "/usr/local/bin/brew" ]; then eval "$(/usr/local/bin/brew shellenv)"; fi' >> $HOME/.zprofile

: # bash
echo >> $HOME/.bash_profile
echo 'if [ -e "/opt/homebrew/bin/brew" ]; then eval "$(/opt/homebrew/bin/brew shellenv)"; fi' >> $HOME/.bash_profile
echo 'if [ -e "/usr/local/bin/brew" ]; then eval "$(/usr/local/bin/brew shellenv)"; fi' >> $HOME/.bash_profile

: # other
echo >> $HOME/.profile
echo 'if [ -e "/opt/homebrew/bin/brew" ]; then eval "$(/opt/homebrew/bin/brew shellenv)"; fi' >> $HOME/.profile
echo 'if [ -e "/usr/local/bin/brew" ]; then eval "$(/usr/local/bin/brew shellenv)"; fi' >> $HOME/.profile

C) Close the window, open a new terminal window, and disable analytics:

brew analytics off

To confirm analytics are disabled, run

brew analytics state

The message should state that analytics are disabled or destroyed.

D) Install NodeJS.

Open the official NodeJS site with a web browser.

NodeJS macOS Installation

In the "Get Node.js®" section:

  1. Select the LTS version (currently "v22.14.0 (LTS)") in the first dropdown

In the "Or get a prebuilt Node.js® for" section:

  1. Select "macOS" from the first dropdown.

  2. Select "ARM64" for Apple Silicon Macs or "x64" for Intel Macs in the second dropdown

  3. Click the green macOS Installer (.pkg) button to download the installer

After the download finishes, open the package and follow the steps to install NodeJS.

Older versions of macOS are not compatible with newer versions of NodeJS.

In local testing, macOS 10.13 required NodeJS version 12.22.12:

curl -LO https://nodejs.org/download/release/v12.22.12/node-v12.22.12.pkg
open node-v12.22.12.pkg

Build from source tree​

  1. Clone the project:
git clone https://git.sheetjs.com/sheetjs/sheetjs
cd sheetjs

On older platforms, the clone may fail due to SSL certificate problems:

fatal: unable to access 'https://git.sheetjs.com/sheetjs/sheetjs/': SSL certificate problem: certificate has expired

The simplest workaround is to disable SSL verification:

git config --global http.sslVerify false

It is strongly recommended to re-enable SSL verification after cloning:

git config --global http.sslVerify true
  1. Install NodeJS modules for building the scripts:
npm i
npm i -g [email protected] voc @sheetjs/uglify-js

If npm i -g fails with a permissions issue, run the command with sudo:

npm i
sudo npm i -g [email protected] voc @sheetjs/uglify-js
Older Versions of Dependencies

Some of the dependencies are wildly out of date. While SheetJS libraries aim to run in older versions of NodeJS and browsers, some libraries have opted to break backwards compatibility. The specific versions are used because they are known to work and known to produce consistent and reproducible results.

  1. Initialize the test files:
rmdir test_files
curl -LO https://test-files.sheetjs.com/test_files.zip
unzip test_files.zip
mkdir -p tmp

The rmdir command may fail if the folder is missing. The error can be ignored.

This step may take a few minutes as the current test snapshot is large.

  1. Run the esbuild tool once:
npx -y [email protected] --version

The command will print the version number 0.14.14.

  1. Run a build and verify with a short test:
: # Full Build
cd modules; make clean; make; cd ..
make
make dist

: # Short test
make test_misc

: # Reset repo
git checkout -- .

In some tests on older releases of macOS, the build failed with an error:

ReferenceError: n is not defined

The first error in the call stack points to dist/xlsx.zahl.js.

Older versions of macOS sed are known to misinterpret newline characters. The workaround is to upgrade to a newer version of sed. On macOS:

brew install gnu-sed
echo 'export PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"' >> ~/.profile
. ~/.profile

Reproduce official builds​

  1. Run git log and search for the commit that matches a particular release version. For example, version 0.20.3 can be found with:
git log | grep -B4 "version bump 0.20.3"

The output should look like:

Expected output
$ git log | grep -B4 "version bump 0.20.3"
commit 8a7cfd47bde8258c0d91df6a737bf0136699cdf8 <-- this is the commit hash
Author: SheetJS <[email protected]>
Date:   Fri Jul 12 11:47:14 2024 -0400

    version bump 0.20.3
  1. Switch to the commit identified by the hash from the previous step:
git checkout 8a7cfd47bde8258c0d91df6a737bf0136699cdf8
  1. Run the full build sequence:
make clean; make
cd modules; make clean; make; cd ..
make
make dist
  1. Verify the scripts by computing the MD5 checksum.

The checksum for the generated xlsx.full.min.js script can be computed using the md5 command on macOS or the md5sum command on WSL and Linux.

md5sum dist/xlsx.full.min.js

The checksum for the equivalent script on the SheetJS CDN can be computed with:

curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5sum -

The following output was captured in win11-arm for SheetJS version 0.20.3:

Expected output
$ md5sum dist/xlsx.full.min.js
6b3130af1ceadf07caa0ec08af7addff  dist/xlsx.full.min.js
$ curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5sum -
6b3130af1ceadf07caa0ec08af7addff  -

The two hashes should match.

  1. Return to the HEAD commit:
git checkout master

Test in web browsers​

  1. Start local server:
make ctestserv

The terminal will display URL. For example:

Expected output
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/)
                                   ^^^^^^^^^^^^^^^^^^^^ URL
  1. Open a browser window and access the displayed URL.

Development​

The xlsx.js and xlsx.mjs files are constructed from the files in the bits subfolder. The build script (run make) will concatenate the individual bits to produce the scripts.

When changing the .js scripts in bits, the following sequence rebuilds the xlsx.js and xlsx.mjs scripts:

make

When changing the .ts scripts in modules, the following sequence rebuilds the xlsx.js and xlsx.mjs scripts:

cd modules; make clean; make; cd ..

To produce the dist files, run make dist.

The various xlsx.* scripts in the base folder and the files in the dist folder are updated on each version release.

They should not be committed between versions!

Tests​

The test_misc target runs the targeted feature tests. It should take 5-10 seconds to perform feature tests without testing against the full test battery. New features should be accompanied with tests for the relevant file formats.

For tests involving the read side, an appropriate feature test would involve reading an existing file and checking the resulting workbook object. If a parameter is involved, files should be read with different values to verify that the feature is working as expected.

For tests involving a new write feature which can already be parsed, appropriate feature tests would involve writing a workbook with the feature and then opening and verifying that the feature is preserved.

For tests involving a new write feature without an existing read ability, please add a feature test to the kitchen sink tests/write.js.