docs.sheetjs.com/docz/docs/03-demos/42-engines/21-boa.md

---
title: Rusty Sheets with Boa
sidebar_label: Rust + Boa
pagination_prev: demos/bigdata/index
pagination_next: solutions/input
---

import current from '/version.js';
import CodeBlock from '@theme/CodeBlock';

:::danger pass

In a production application, it is strongly recommended to use a binding for a
more performant engine like [`v8`](/docs/demos/engines/v8#rust)

:::

[Boa](https://boajs.dev/) is a JavaScript engine written in Rust.

[SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing
data from spreadsheets.

The ["Complete Example"](#complete-example) section creates a command-line tool
for reading data from spreadsheets and generating CSV rows.

## Integration Details

### Initialize Boa

A JS context can be constructed in one line:

```rust
/* initialize */
let context = &mut boa_engine::Context::default();
```

The following helper function evaluates strings as JS code:

```rust
/* simple wrapper to evaluate code snippets */
fn eval_code(c: &mut boa_engine::Context, code: &str) -> Result<std::string::String, boa_engine::JsError> {
  let src = boa_engine::Source::from_bytes(code);
  match c.eval(src) {
    Ok(res) => { return Ok(res.to_string(c).unwrap().to_std_string_escaped()); }
    Err(e) => { return Err(e); }
  };
}
```

### Load SheetJS Scripts

The [SheetJS Standalone scripts](/docs/getting-started/installation/standalone)
can be parsed and evaluated in a Boa context.

Boa provides a special helper `boa_engine::Source::from_filepath` to read source
code from a path, but it is recommended to inline the SheetJS standalone script
using the `include_str!` macro:

```rust
  /* load library */
  match eval_code(context, include_str!("../xlsx.full.min.js")) {
    Ok(_res) => {}
    Err(e) => { return eprintln!("Uncaught {e}"); }
  }
```

To confirm the library is loaded, `XLSX.version` can be inspected:

```rust
  /* get version string */
  match eval_code(context, "XLSX.version") {
    Ok(res) => { println!( "SheetJS library version {}", res); }
    Err(e) => { return eprintln!("Uncaught {e}"); }
  }
```

### Reading Files

Boa supports `ArrayBuffer` natively.  This snippet reads data from a file into
`Vec<u8>` and stores the data as an `ArrayBuffer` in global scope:

```rust
  /* read file */
  let data: Vec<u8> = std::fs::read("pres.xlsx").unwrap();
  let array: boa_engine::object::builtins::JsArrayBuffer = boa_engine::object::builtins::JsArrayBuffer::from_byte_block(file, context).unwrap();
  let attrs = boa_engine::property::Attribute::WRITABLE | boa_engine::property::Attribute::ENUMERABLE | boa_engine::property::Attribute::CONFIGURABLE;
  let _ = context.register_global_property(boa_engine::js_string!("buf"), array, attrs);

  /* parse with SheetJS */
  match eval_code(context, "void (globalThis.wb = XLSX.read(buf))") {
    Ok(_res) => { }
    Err(e) => { return eprintln!("Uncaught {e}"); }
  }
```

`wb` will be a variable in the JS environment that can be inspected using the
various SheetJS API functions.

## Complete Example

:::note Tested Deployments

This demo was tested in the following deployments:

| Architecture | Boa      | Date       |
|:-------------|:---------|:-----------|
| `darwin-x64` | `0.20.0` | 2025-03-31 |
| `darwin-arm` | `0.20.0` | 2025-09-03 |
| `win11-x64`  | `0.20.0` | 2025-04-28 |
| `win11-arm`  | `0.20.0` | 2025-02-23 |
| `linux-x64`  | `0.20.0` | 2025-04-21 |
| `linux-arm`  | `0.20.0` | 2025-02-15 |

:::

0) Install Rust.

:::caution pass

Boa `0.18.0` requires Rust version `1.67` or later.

Debian 12 (Bullseye) ships with Rust version `1.63.0`.

It is strongly recommended to install Rust from the official distribution.

:::

1) Create a new project:

```bash
cargo new sheetjs-boa
cd sheetjs-boa
cargo run
```

2) Add the `boa_engine` crate:

```bash
cargo add boa_engine
```

3) Download the SheetJS Standalone script and test file. Save both files in the
project directory:

<ul>
<li><a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js`}>xlsx.full.min.js</a></li>
<li><a href="https://docs.sheetjs.com/pres.xlsx">pres.xlsx</a></li>
</ul>

<CodeBlock language="bash">{`\
curl -LO https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js
curl -LO https://docs.sheetjs.com/pres.xlsx`}
</CodeBlock>

:::caution pass

PowerShell `curl` is incompatible with the official `curl` program. The command
may fail with a parameter error:

```
Invoke-WebRequest : A parameter cannot be found that matches parameter name 'LO'.
```

`curl.exe` must be used instead:

<CodeBlock language="bash">{`\
curl.exe -LO https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js
curl.exe -LO https://docs.sheetjs.com/pres.xlsx`}
</CodeBlock>

:::

4) Download [`main.rs`](pathname:///boa/main.rs) and replace `src/main.rs`:

```bash
curl -L -o src/main.rs https://docs.sheetjs.com/boa/main.rs
```

:::caution pass

PowerShell `curl` is incompatible with the official `curl` program. The command
may fail with a parameter error:

```
Invoke-WebRequest : A parameter cannot be found that matches parameter name 'LO'.
```

`curl.exe` must be used instead:

```bash
curl.exe -L -o src/main.rs https://docs.sheetjs.com/boa/main.rs
```

:::

5) Build and run the app in release mode:

```bash
cargo run --release pres.xlsx
```

After a short wait, the contents will be displayed in CSV form.

:::caution pass

The default debug build is not optimized and can elicit stack overflow errors.
It is strongly encouraged to use `--release` when possible.

:::