---
title: Bun
pagination_prev: getting-started/index
pagination_next: getting-started/examples/index
sidebar_position: 7
sidebar_custom_props:
  summary: Load NodeJS-style modules using CommonJS or ESM
---

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

Tarballs are available on <https://cdn.sheetjs.com>.

<p><a href={`https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}>https://cdn.sheetjs.com/xlsx-{current}/xlsx-{current}.tgz</a> is the URL for version {current}</p>

:::caution Bun support is considered experimental.

Great open source software grows with user tests and reports. Any issues should
be reported to the Bun project for further diagnosis.

:::

## Installation

Tarballs can be directly installed with `bun install`[^1]:

<CodeBlock language="bash">{`\
bun install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>

:::tip pass

[Watch the repo](https://git.sheetjs.com/SheetJS/sheetjs) or subscribe to the
[RSS feed](https://git.sheetjs.com/sheetjs/sheetjs/tags.rss) to be notified when
new versions are released!

:::

:::warning pass

At the time of writing `bun install` does not support vendored tarballs[^2].

:::

## Usage

Bun supports both "CommonJS" and "ESM" modules.

:::info pass

**It is strongly recommended to use CommonJS in Bun.**

:::

#### CommonJS `require`

By default, the module supports `require` and it will automatically add support
for streams and file system access:

```js
const { readFile } = require("xlsx");
const wb = readFile("pres.numbers"); // works!
```

#### ESM `import`

When importing the library using ESM `import` statements, the native NodeJS
modules are not loaded. They must be added manually:

```js
import * as XLSX from 'xlsx';

/* load 'fs' for readFile and writeFile support */
import * as fs from 'fs';
XLSX.set_fs(fs);

/* load 'stream' for stream support */
import { Readable } from 'stream';
XLSX.stream.set_readable(Readable);

/* load the codepage support library for extended support with older formats  */
import * as cpexcel from 'xlsx/dist/cpexcel.full.mjs';
XLSX.set_cptable(cpexcel);
```

[^1]: Bun releases before the official 1.0.0 release did not support tarball dependencies. If a pre-1.0.0 release must be used, the [ES Module script can be vendored](/docs/getting-started/installation/standalone#ecmascript-module-imports) or the [NodeJS module can be installed with a NodeJS-compatible package manager](/docs/getting-started/installation/nodejs).
[^2]: See [the relevant issue in the Bun issue tracker](https://github.com/oven-sh/bun/issues/101)