syntaxbullet/docs.sheetjs.com
1
Fork 0
forked from sheetjs/docs.sheetjs.com
Code Pull Requests Activity

Darwin / Linux contributing scripts

Browse Source
This commit is contained in:
SheetJS 2026-03-05 23:51:03 -05:00
parent d922ad6246
commit a0e35dd7e1
6 changed files with 271 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
docz/docs/03-demos/32-extensions/05-vscode.md
View File

@ -1,11 +1,11 @@
---
title: Visualizing Data in VS Code
sidebar_label: Visual Studio Code
description: View Excel files directly in VS Code. Seamlessly browse spreadsheet data without leaving your editor using SheetJS. Navigate between worksheets and pages of data with a responsive
description: View Excel files directly in VS Code. Seamlessly browse spreadsheet data using SheetJS. Navigate between worksheets and pages of data with a responsive interface.
pagination_prev: demos/cloud/index
pagination_next: demos/bigdata/index
sidebar_custom_props:
summary: View Excel files directly within Visual Studio Code
summary: View Excel spreadsheets directly within Visual Studio Code
---
import current from '/version.js';
@ -21,13 +21,14 @@ that supports JavaScript extensions for customizing and enhancing functionality.
The ["Complete Example"](#complete-example) uses SheetJS in a VS Code extension
to view Excel files directly within the editor. The extension leverages the VS
Code "Custom Editor API"[^2] and "WebView API"[^1] to display spreadsheet data
Code "WebView API"[^1] and "Custom Editor API"[^2] to display spreadsheet data
as HTML tables.
:::tip pass
["SheetJS Spreadsheet Viewer"](https://marketplace.visualstudio.com/items?itemName=asadbek.sheetjs-demo)
is a sample extension based on this demo.
"SheetJS Spreadsheet Viewer" is a sample extension based on this demo. It is
available on [Open VSX](https://open-vsx.org/extension/asadbek/sheetjs-demo) and
[VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=asadbek.sheetjs-demo)
[The source code](https://git.sheetjs.com/asadbek064/sheetjs-vscode-extension)
is available on the SheetJS Git server. Feedback and contributions are welcome!
@ -40,13 +41,11 @@ is available on the SheetJS Git server. Feedback and contributions are welcome!
This demo was verified in the following deployments:
| Platform | Architecture | Date |
|:-----------------|:-------------|:-----------|
| VS Code 1.100.0 | `darwin-arm` | 2025-05-15 | TODO
| VSCodium 1.100.0 | `darwin-arm` | 2025-05-15 | TODO
| Cursor | `win11-arm` | 2025-05-15 | TODO
| Windsurf | `win11-arm` | 2025-05-15 | TODO
| Void | `win11-arm` | 2025-05-15 | TODO
| Platform | Architecture | Date |
|:-------------------|:-------------|:-----------|
| VSCodium 1.109 | `darwin-arm` | 2026-03-05 |
| VS Code 1.110.0 | `win11-arm` | 2026-03-05 |
| Antigravity 1.19.6 | `linux-arm` | 2026-03-05 |
:::
@ -57,30 +56,36 @@ imported from any component or script in the extension.
:::caution pass
The module must be installed as a development dependency. If the module is
installed as a normal dependency, `vsce`[^5] (Visual Studio Code Extension
Manager) will fail to package or publish your extension correctly.
The SheetJS NodeJS module must be installed as a development dependency. If the
module is installed as a normal dependency, the `vsce`[^3] command-line tool
will fail to package or publish the exxtension.
<Tabs groupId="pm">
<TabItem value="npm" label="npm">
<CodeBlock language="bash">{`\
<Tabs groupId="pm">
<TabItem value="npm" label="npm">
<CodeBlock language="bash">{`\
npm rm --save xlsx
npm i --save-dev https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>
</TabItem>
<TabItem value="pnpm" label="pnpm">
<CodeBlock language="bash">{`\
</CodeBlock>
</TabItem>
<TabItem value="pnpm" label="pnpm">
<CodeBlock language="bash">{`\
pnpm rm xlsx
pnpm install -D https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>
</TabItem>
<TabItem value="yarn" label="Yarn" default>
<CodeBlock language="bash">{`\
</CodeBlock>
</TabItem>
<TabItem value="yarn" label="Yarn" default>
<CodeBlock language="bash">{`\
yarn remove xlsx
yarn add -D https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>
</CodeBlock>
</TabItem>
</Tabs>
</Tabs>
:::
@ -112,11 +117,11 @@ export function activate(context: vscode.ExtensionContext) {
context.subscriptions.push(provider);
// highlight-end
}
export function deactivate() {}`}
export function deactivate() {}
```
The `custom editor`[^3] is configured to support specific file types, giving us complete control over how each file is
presented to the user. Additionally, `custom document`[^4] enables us to maintain and persist the state of each individual
The `custom editor`[^4] is configured to support specific file types, giving us complete control over how each file is
presented to the user. Additionally, `custom document`[^5] enables us to maintain and persist the state of each individual
file that's opened.
<CodeBlock language="typescript" value="typescript" title="src/excelEditorProvider.ts">
@ -205,7 +210,17 @@ sequenceDiagram
## Complete Example
1) Create a new VS Code extension
:::caution pass
To avoid conflicts with existing extensions, it is strongly recommended to test
with a different VSCode fork. For example, VSCode and Antigravity users should
install and use VSCodium for extension development.
:::
1) Download the [`pres.xlsx`](https://docs.sheetjs.com/pres.xlsx) sample file.
2) Create a new VS Code extension
```bash
npx --package yo --package generator-code -- yo code
@ -215,17 +230,15 @@ When prompted, enter the following options:
- `What type of extension do you want to create?`: Select `New Extension (TypeScript)` and press <kbd>Enter</kbd>
- `What's the name of your extension?`: Type `sheetjs-demo` and press <kbd>Enter</kbd>
- `What's the identifier of your extension?`: Press <kbd>Enter</kbd>
- `What's the description of your extension?`: Press <kbd>Enter</kbd>
- `What's the identifier of your extension?`: Press <kbd>Enter</kbd> (use the default `sheetjs-demo`)
- `What's the description of your extension?`: Press <kbd>Enter</kbd> (leave blank)
- `Initialize a git repository?`: Type `n` and press <kbd>Enter</kbd>
- `Which bundler to use?`: Select `webpack` and press <kbd>Enter</kbd>
- `Which package manager to use?`: Select `pnpm` and press <kbd>Enter</kbd>
![Expected output](pathname:///vscode/yeo-code.png)
- `Do you want to open the new folder with Visual Studio Code?`: Press <kbd>Enter</kbd>
2) [Install the dependencies](#integration-details) and start the dev server:
3) Install the SheetJS library and start the dev server:
<CodeBlock language="bash">{`\
cd sheetjs-demo
@ -234,9 +247,12 @@ pnpm run watch
`}
</CodeBlock>
3) Save the following code snippet to `src/excelEditorProvider.ts`:
4) Launch a new editor window using the desired VSCode fork and open the newly
created `sheetjs-demo` folder.
<CodeBlock language="typescript" value="typescript" title="src/excelEditorProvider.ts">{`\
4) Save the following codeblock to `src/extension.ts`:
```ts title="src/extension.ts (replace contents)"
import * as vscode from 'vscode';
import * as XLSX from 'xlsx';
@ -245,16 +261,14 @@ class ExcelDocument implements vscode.CustomDocument {
dispose() { }
}
export class ExcelEditorProvider implements vscode.CustomReadonlyEditorProvider<ExcelDocument> {
public static register(context: vscode.ExtensionContext): vscode.Disposable {
return vscode.window.registerCustomEditorProvider(
'excelViewer.spreadsheet',
new ExcelEditorProvider(),
{ webviewOptions: { retainContextWhenHidden: true } } // keep webview state when hidden
);
class ExcelEditorProvider implements vscode.CustomReadonlyEditorProvider<ExcelDocument> {
// This is called when the first time an editor for a given resource is opened
async openCustomDocument(uri: vscode.Uri): Promise<ExcelDocument> {
return new ExcelDocument(uri);
}
private async loadWorkbook(document: ExcelDocument, webviewPanel: vscode.WebviewPanel): Promise<XLSX.WorkBook> {
// This is called whenever the user opens a new editor
async resolveCustomEditor(document: ExcelDocument, webviewPanel: vscode.WebviewPanel): Promise<void> {
const data: Uint8Array = await vscode.workspace.fs.readFile(document.uri);
const options: XLSX.ParsingOptions = {
@ -263,41 +277,26 @@ export class ExcelEditorProvider implements vscode.CustomReadonlyEditorProvider<
cellDates: true,
};
return XLSX.read(new Uint8Array(data), options); // returns a XLSX.WorkBook
}
// This is called when the first time an editor for a given resource is opened
async openCustomDocument(uri: vscode.Uri): Promise<ExcelDocument> {
return new ExcelDocument(uri);
}
// This is called whenever the user opens a new editor
async resolveCustomEditor(document: ExcelDocument, webviewPanel: vscode.WebviewPanel): Promise<void> {
const wb: XLSX.WorkBook = await this.loadWorkbook(document, webviewPanel);
const wb: XLSX.WorkBook = XLSX.read(new Uint8Array(data), options);
const htmlTable = XLSX.utils.sheet_to_html(wb.Sheets[wb.SheetNames[0]]);
webviewPanel.webview.html = \`<!DOCTYPE html><html><body>\${htmlTable}</body></html>\`;
webviewPanel.webview.html = `<!DOCTYPE html><html><body>${htmlTable}</body></html>`;
}
}`}
</CodeBlock>
4) Register the custom editor provider in `src/extension.ts`:
<CodeBlock language="typescript" value="typescript" title="src/extension.ts (replace contents)">{`\
import * as vscode from 'vscode';
import { ExcelEditorProvider } from './excelEditorProvider';
}
export function activate(context: vscode.ExtensionContext) {
// SheetJS Spreadsheet Viewer extension activating...
const provider = ExcelEditorProvider.register(context);
const provider = vscode.window.registerCustomEditorProvider(
'excelViewer.spreadsheet',
new ExcelEditorProvider(),
{ webviewOptions: { retainContextWhenHidden: true } } // keep webview state when hidden
);
context.subscriptions.push(provider);
}
export function deactivate() {}`}
</CodeBlock>
export function deactivate() {}
```
5) Register the custom editor in the `contributes` section of `package.json`:
5) Add the highlighted lines to the `contributes` section of `package.json`:
<CodeBlock language="json" value="json" title="package.json (add highlighted lines)">{`\
"main": "./dist/extension.js",
```json title="package.json (add highlighted lines)"
"contributes": {
// highlight-start
"customEditors": [
@ -318,19 +317,38 @@ export function deactivate() {}`}
}
]
},
`}
</CodeBlock>
```
6. Inside the editor, open `src/extension.ts` and press <kbd>F5</kbd> or run the command **Debug: Start Debugging**
from the Command Palette (<kbd>⇧⌘P</kbd>). This will compile and run the extension in a new Extension Development Host window.
6) In the editor, open the Command Palette (Help > "Show All Commands" from the
menu), type `Debug: Start` and select `Debug: Start Debugging`.
7. Select the new VSCode Window and open a `.xlsx` or `.xls` file.
This will compile and run the extension in a new Extension Development Host window.
7) Drag and drop the `pres.xlsx` test file into the new window. If drag and drop
is not available, click "Open..." in the Welcome screen and select the file.
---
A new `pres.xlsx` tab will show the contents of the file.
[^1]: See [`Webview API`](https://code.visualstudio.com/api/extension-guides/webview) for more details.
[^2]: See [`Custom Editor API`](https://code.visualstudio.com/api/extension-guides/custom-editors) documentation for more details.
[^3]: See [`Custom Editor`](https://code.visualstudio.com/api/extension-guides/custom-editors#custom-editor) for more details.
[^4]: See [`CustomDocument`](https://code.visualstudio.com/api/extension-guides/custom-editors#customdocument) for more details.
[^5]: See [`Visual Studio Code Extension Manager`](https://code.visualstudio.com/api/working-with-extensions/publishing-extension) for more details.
:::info pass
When this demo was last tested, the default project assumed VSCode version
1.109.0 or later. Antigravity 1.19.6 is aligned to VSCode 1.107.0. The default
extension will not run in Antigravity.
This can be fixed by changing the `vscode` field in `package.json`. When this
demo was last tested, it was safe to set a minimum version of `^1.100.0`:
```json title="package.json (change highlighted line)"
"engines": {
// highlight-next-line
"vscode": "^1.100.0"
}
```
:::
[^1]: See [`Webview API`](https://code.visualstudio.com/api/extension-guides/webview) in the VSCode documentation for more details.
[^2]: See [`Custom Editor API`](https://code.visualstudio.com/api/extension-guides/custom-editors) in the VSCode documentation for more details.
[^3]: See [`vsce`](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#vsce) in the VSCode documentation for more details.
[^4]: See [`Custom Editor`](https://code.visualstudio.com/api/extension-guides/custom-editors#custom-editor) in the VSCode documentation for more details.
[^5]: See [`CustomDocument`](https://code.visualstudio.com/api/extension-guides/custom-editors#customdocument) in the VSCode documentation for more details.

4
docz/docs/03-demos/42-engines/02-v8.md
View File

@ -1666,8 +1666,8 @@ This demo was last tested in the following deployments:
|:-------------|:--------------|:---------|:-----------|
| `darwin-x64` | `14.4` | `3.13.7` | 2026-03-04 |
| `darwin-arm` | `14.4` | `3.14.3` | 2026-03-04 |
| `win11-x64` | `14.4` | `3.11.9` | 2026-02-04 |
| `win11-arm` | `14.4` | `3.11.9` | 2026-02-04 |
| `win11-x64` | `14.4` | `3.11.9` | 2026-03-05 |
| `win11-arm` | `14.4` | `3.11.9` | 2026-03-05 |
| `linux-x64` | `14.4` | `3.13.9` | 2026-03-04 |
| `linux-arm` | `14.4` | `3.13.5` | 2026-03-04 |

2
docz/docs/09-miscellany/05-contributing.md
View File

@ -42,7 +42,7 @@ These instructions were tested on the following platforms:
| Platform | Architecture | Test Date |
|:------------------------------|:-------------|:-----------|
| Linux (Ubuntu Linux x64) | `linux-x64` | 2026-02-02 |
| Linux (Debian Linux AArch64) | `linux-arm` | 2025-01-14 |
| Linux (Debian Linux AArch64) | `linux-arm` | 2026-03-05 |
| MacOS 15.6 (x64) | `darwin-x64` | 2026-01-21 |
| MacOS 15.7 (ARM64) | `darwin-arm` | 2026-02-02 |
| Windows 11 (x64) + WSL Ubuntu | `win11-x64` | 2025-06-20 |

74
tests/contributing/darwin.sh Executable file
View File

@ -0,0 +1,74 @@
#!/bin/bash
# https://docs.sheetjs.com/docs/miscellany/contributing
SHEETJS_VERSION="0.20.3"
OS="$(uname -s)"
case "$OS" in
Darwin) ;;
*) echo "unsupported OS: $OS"; exit 1 ;;
esac
cd /tmp
git --version || { echo "Git not found. Please install Xcode command-line tools."; exit 1; }
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
if ! command -v nvm &> /dev/null; then curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash; fi
if ! command -v node &> /dev/null; then nvm install --lts; fi
nvm use --lts
node --version
if [ ! -e sheetjs ]; then
if ! git clone https://git.sheetjs.com/sheetjs/sheetjs 2>&1; then
git config --global http.sslVerify false
git clone https://git.sheetjs.com/sheetjs/sheetjs 2>&1
git config --global http.sslVerify true
fi
fi
cd sheetjs
npm i
npm i -g mocha@2.5.3 voc @sheetjs/uglify-js || sudo npm i -g mocha@2.5.3 voc @sheetjs/uglify-js
rmdir test_files 2>/dev/null || rm -rf test_files
curl -LO https://test-files.sheetjs.com/test_files.zip
unzip -q test_files.zip
mkdir -p tmp
npx -y esbuild@0.14.14 --version
cd modules; make clean; make; cd ..
make
make dist
make test_misc
for file in dist/xlsx.full.min.js xlsx.js xlsx.mjs; do
if ! stat "$file" > /dev/null 2>&1; then echo "ERROR: $file not found"; exit 1; fi
done
git checkout -- .
COMMIT_HASH=$(git log | grep -B4 "version bump $SHEETJS_VERSION" | head -1 | awk '{print $2}')
if [ -z "$COMMIT_HASH" ]; then echo "ERROR: Could not find commit for version $SHEETJS_VERSION"; exit 1; fi
echo "Version $SHEETJS_VERSION : Commit $COMMIT_HASH"
git checkout "$COMMIT_HASH"
make clean; make
cd modules; make clean; make; cd ..
make
make dist
LOCAL_MD5=$(md5 dist/xlsx.full.min.js | awk '{print $4}')
CDN_MD5=$(curl -k -L "https://cdn.sheetjs.com/xlsx-$SHEETJS_VERSION/package/dist/xlsx.full.min.js" | md5)
echo "Local MD5: $LOCAL_MD5"
echo "CDN MD5: $CDN_MD5"
if [ "$LOCAL_MD5" != "$CDN_MD5" ]; then echo "ERROR: MD5 checksums do not match!"; exit 1; fi
git checkout master

90
tests/contributing/linux.sh Executable file
View File

@ -0,0 +1,90 @@
#!/bin/bash
# https://docs.sheetjs.com/docs/miscellany/contributing
SHEETJS_VERSION="0.20.3"
OS="$(uname -s)"
case "$OS" in
Linux) ;;
*) echo "unsupported OS: $OS"; exit 1 ;;
esac
cd /tmp
MISSING_PKGS=""
for cmd in gcc make curl git unzip; do
if ! command -v "$cmd" &> /dev/null; then
case "$cmd" in
gcc) MISSING_PKGS="$MISSING_PKGS build-essential" ;;
*) MISSING_PKGS="$MISSING_PKGS $cmd" ;;
esac
fi
done
if [ -n "$MISSING_PKGS" ]; then
echo "The following Debian/Ubuntu packages are missing: $MISSING_PKGS"
# sudo apt-get update
# sudo apt-get install -y $MISSING_PKGS
exit 1
fi
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
if ! command -v nvm &> /dev/null; then curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash; fi
if ! command -v node &> /dev/null; then nvm install --lts; fi
nvm use --lts
node --version
if [ ! -e sheetjs ]; then
if ! git clone https://git.sheetjs.com/sheetjs/sheetjs 2>&1; then
git config --global http.sslVerify false
git clone https://git.sheetjs.com/sheetjs/sheetjs 2>&1
git config --global http.sslVerify true
fi
fi
cd sheetjs
npm i
npm i -g mocha@2.5.3 voc @sheetjs/uglify-js || sudo npm i -g mocha@2.5.3 voc @sheetjs/uglify-js
rmdir test_files 2>/dev/null || rm -rf test_files
curl -LO https://test-files.sheetjs.com/test_files.zip
unzip -q test_files.zip
mkdir -p tmp
npx -y esbuild@0.14.14 --version
cd modules; make clean; make; cd ..
make
make dist
make test_misc
for file in dist/xlsx.full.min.js xlsx.js xlsx.mjs; do
if ! stat "$file" > /dev/null 2>&1; then echo "ERROR: $file not found"; exit 1; fi
done
git checkout -- .
COMMIT_HASH=$(git log | grep -B4 "version bump $SHEETJS_VERSION" | head -1 | awk '{print $2}')
if [ -z "$COMMIT_HASH" ]; then echo "ERROR: Could not find commit for version $SHEETJS_VERSION"; exit 1; fi
echo "Version $SHEETJS_VERSION : Commit $COMMIT_HASH"
git checkout "$COMMIT_HASH"
make clean; make
cd modules; make clean; make; cd ..
make
make dist
LOCAL_MD5=$(md5sum dist/xlsx.full.min.js | awk '{print $1}')
CDN_MD5=$(curl -L "https://cdn.sheetjs.com/xlsx-$SHEETJS_VERSION/package/dist/xlsx.full.min.js" | md5sum | awk '{print $1}')
echo "Local MD5: $LOCAL_MD5"
echo "CDN MD5: $CDN_MD5"
if [ "$LOCAL_MD5" != "$CDN_MD5" ]; then echo "ERROR: MD5 checksums do not match!"; exit 1; fi
git checkout master

4
tests/engines/miniracer.ps1
View File

@ -8,9 +8,7 @@ New-Item -ItemType Directory -Path $tempDir | Out-Null
Set-Location -Path $tempDir
pip install mini-racer 2>&1 | Out-Null
if ($LASTEXITCODE -ne 0) {
python -m pip install mini-racer
}
if ($LASTEXITCODE -ne 0) { python -m pip install mini-racer }
Invoke-WebRequest -Uri "https://cdn.sheetjs.com/xlsx-latest/package/dist/xlsx.full.min.js" -OutFile "xlsx.full.min.js"
Invoke-WebRequest -Uri "https://docs.sheetjs.com/pres.xlsx" -OutFile "pres.xlsx"