Excel-Builder-Vanilla

Documentation

📘 Documentation website powered by GitBook (previous project docs were pulled from web archive)

Description

This lib allows you to build and write an Excel file dynamically, it does not include any reader capabilities making the library super lightweight for its main goal of strictly exporting to Excel.

Comparison to similar libraries

Excel-buider-vanilla is at the minimum 8x times smaller than the most popular libraries (we used Bundlephobia to compare), excel-builder-vanilla is 16.5Kb gzip while XLSX is 136Kb and ExcelJS is 251Kb gzip. The reason as to why it's much smaller is very simple and relates to these 2 major differences:

• excel-builder-vanilla is ESM-Only (tree shakable) and all other libraries are just offering CJS (CommonJS) increasing their download/install size (not tree shakable)
• excel-builder-vanilla only offers Excel export (writer) but without any reading capabilities

Live Demo

Visit the Live demo to get started and see all available options and methods that the library offers (all the demos are WYSIWYG (what you is what you'll get, UI vs Export)).
You can also take a look at the "Used by" section below to see real world applications taking advantage of this library.

License

MIT License

Installation

npm install excel-builder-vanilla

The project offers 3 different build types, choose the best one depending on your use case

1. ESM: to import from (preferred)
2. IIFE: standalone script which provides ExcelBuilder on the window object

// ESM (preferred) - npm install
import { createWorksheet } from 'excel-builder-vanilla';

// IIFE - CDN
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/excel-builder.iife.js"></script>
<script>
  const worksheet = ExcelBuilder.createWorksheet(); // or window.ExcelBuilder.createWorksheet();
</script>

CSP (Content Security Policy)

Please note that since we use fflate (which creates and compresses the Excel file before sending it to the browser), you might get some CSP errors because of its use of Web Workers. For that reason, you might need to adjust your CSP rules by adding worker-src 'self' blob:;

<meta http-equiv="Content-Security-Policy"
  content="default-src 'self';
  worker-src 'self' blob:;" />

Basic Usage

import { Workbook, downloadExcelFile } from 'excel-builder-vanilla';

const originalData = [
  ['Artist', 'Album', 'Price'],
  ['Buckethead', 'Albino Slug', 8.99],
  ['Buckethead', 'Electric Tears', 13.99],
  ['Buckethead', 'Colma', 11.34],
];
const artistWorkbook = new Workbook();
const albumList = artistWorkbook.createWorksheet({ name: 'Artists' });
albumList.setData(originalData);
artistWorkbook.addWorksheet(albumList);

downloadExcelFile(artistWorkbook, 'Artist WB.xlsx');

Project History

Excel-Builder-Vanilla is a fork of the popular excel-builder.js project (thanks to @stephenliberty for this great library). The main goal of creating this fork was to modernize the project by removing old dependencies that are no longer necessary and also replace JSZip by fflate which provides an ESM build and is indirectly giving us better Tree Shaking. The other goal was also to provide an ESM build

The modernization steps:

• migrate to TypeScript (which is giving us TS Types d.ts)
• drop Q dependency (we now simply use native Promise)
• drop Lodash dependency (we now use native JS code)
• replace JSZip dependency with fflate which has an ESM build and offers better performance.
• bump version to v3.0.0 as a major release (the original project version was in the 2.x range.)
  • note that the changelog did not exists prior to v3.0.0

The project now requires only 1 small dependency which is fflate.

Summary

This modernization is providing a huge decrease in the final build size, with only 1 dependency, and also offers better performance 🚀

Used by

This fork was created mostly to support Tree Shaking (ESM), to provide TS Types and finally to update all project dependencies. It is used by a few other Open Source libraries that I also maintain and require Excel export:

• Angular-Slickgrid
• Aurelia-Slickgrid
• Slickgrid-React
• Slickgrid-Universal

Contributions

Pull Request are welcome, feel free to contribute.

Development / Contributions

If you wish to contribute to the project, please follow the steps below:

Note: this project uses pnpm workspaces, you can install pnpm by following their installation or use NodeJS corepack enable to run any of the pnpm scripts shown below:

1. clone the lib:
   • git clone https://github.com/ghiscoding/excel-builder-vanilla
2. install it with pnpm from the project root:
   • pnpm install OR npx pnpm install
3. run a full TypeScript build
   • pnpm run build OR npx pnpm run build
4. run in development mode (lib & demo)
   • pnpm run dev OR npx pnpm run dev

Pull Request Contribution

Before submitting a PR (pull request), please make sure that you followed these steps for a better chance of a successfull PR:

1. make sure that you have already executed pnpm install
2. run the Biome lint npm script (or simply use step 4)
   • pnpm run biome:lint:write
3. run the Biome code formatting npm script (or simply use step 4)
   • pnpm run biome:format:write
4. run a full Build (this will also run Biome lint/format, so you could skip step 2)
   • pnpm run build

Packages

Package Name	NPM downloads	Size (gzip)	Changes	Description
excel-builder-vanilla			changelog	excel-builder-vanilla library package
excel-builder-vanilla-types			changelog	excel-builder-vanilla dts types only package.

Sponsors