XLSX-Wasm-Parser
A WebAssembly wrapper over the Rust Calamine crate, bringing Blazingly Fast (π₯) XLSX deserialization for Excel-files to both the browser and NodeJS.
About
This project is designed for deserializing XLSX files in the browser and Node. It takes the bytes of a file and returns either a 2D array of cells, or a list of objects based on a passed schema, which can be validated through built-in integration with Zod.
Can I use this in production?
This project is still in it's early stages, and only implements the bare essentials for deserializing XLSX files. If all you need is to either get all rows from a file, or getting rows based on a schema, you can use this library as I won't be making breaking changes to the current public interface. However if you need full support for all XLSX features today, please consider using read-excel-file instead. If you have any feature requests, please open an issue. If you would like to contribute, please open a PR.
π΄ Usage
π Install via NPM
npm install xlsx-wasm-parser
Set-up with Webpack
We need to enable experimental WASM support in Webpack. To do this, add the following to your Webpack config:
module.exports = {
experiments: {
...,
asyncWebAssembly: true,
topLevelAwait: true,
},
};
Set-up with NextJS
For NextJS we need to enable WASM-support in the Webpack-bundler, which can be done by adding the following to your next.config.js
-file
const config = {
...
webpack: (config) => {
config.experiments = { ...config.experiments, asyncWebAssembly: true, topLevelAwait: true };
return config;
},
};
β‘ Set-up with Vite
Vite requires the vite-plugin-wasm to run WebAssembly, which in turn requires the vite-plugin-top-level-await plugin. To use this library with Vite, you must install both of these plugins and add them to your Vite config.
npm i -D vite-plugin-wasm vite-plugin-top-level-await
import wasm from "vite-plugin-wasm";
import topLevelAwait from "vite-plugin-top-level-await";
export default defineConfig({
plugins: [wasm(), topLevelAwait()],
});
SSR & SSG
Since the code might run on both the server and the client, we need to dynamically import the library based on the environment. This can be done by using the following code:
const { getAllRows } =
typeof window === "undefined"
? await import("xlsx-wasm-parser/node")
: await import("xlsx-wasm-parser");
π Usage in the browser
Getting all rows
import { getAllRows } from "xlsx-wasm-parser";
const input = document.getElementById("input");
input.addEventListener("change", () => {
input.files?.[0]?
.arrayBuffer()
.then(getAllRows)
.then((rows) => {
});
});
fetch("https://example.com/file.xlsx")
.then((response) => response.arrayBuffer())
.then(getAllRows)
.then((rows) => {
});
Getting rows based on a schema
import { getParsedRows } from "xlsx-wasm-parser";
const xlsxSchema = [
[0, "name"],
[1, "age"],
[2, "address"]
] as [number, string][];
const input = document.getElementById("input");
input.addEventListener("change", () => {
input.files?.[0]?
.arrayBuffer()
.then((buffer) => getRows(buffer, xlsxSchema))
.then((rows) => {
});
});
To use the validation feature, import the getParsedRowsWithZodSchema
function from the validation
entry-point.
With Zod Validation
import { getParsedRowsWithZodSchema} from "xlsx-wasm-parser/validation";
import z from "zod";
const xlsxSchema = [
[0, "name"],
[1, "age"],
[2, "address"]
] as [number, string][];
const zodSchema = z.object({
name: z.string(),
age: z.number(),
address: z.string(),
});
const input = document.getElementById("input");
input.addEventListener("change", () => {
input.files?.[0]?
.arrayBuffer()
.then((buffer) => getRowsWithZodSchema(buffer, xlsxSchema, zodSchema))
.then((rows) => {
});
});
π¦ Usage in Node
To use the Node version of this package, import it from the Node entry-point.
Getting all rows
import { getAllRows } from "xlsx-wasm-parser/node";
import fs from "fs";
const rows = getAllRows(fs.readFileSync("file.xlsx"));
Getting rows based on a schema
import { getParsedRows } from "xlsx-wasm-parser/node";
import fs from "fs";
const xlsxSchema = [
[0, "name"],
[1, "age"],
[2, "address"],
] as [number, string][];
const rows = getParsedRows(fs.readFileSync("file.xlsx"), xlsxSchema);
To use the validation feature for Node, import the getParsedRowsWithZodSchema
function from the node/validation
entry-point.
With Zod Validation
import { getParsedRowsWithZodSchema } from "xlsx-wasm-parser/node/validation";
import fs from "fs";
const xlsxSchema = [
[0, "name"],
[1, "age"],
[2, "address"],
] as [number, string][];
const zodSchema = z.object({
name: z.string(),
age: z.number(),
address: z.string(),
});
const rows = getParsedRowsWithZodSchema(
fs.readFileSync("file.xlsx"),
xlsxSchema,
zodSchema
);
Benchmarks
Coming soon! I need to write fair implementations of the other libraries first. However from what I've been able to measure so far I can tell you it's fast.
Contributing
Currently there is a lot to do so all contributions are appreciated!