Requesting ECMAScript module (ESM) bundle support

[endigo9740]

EDIT: Please read and follow the instructions at https://docs.sheetjs.com/docs/getting-started/installation/frameworks before raising a new issue.

When this issue was raised, the module only shipped with a CommonJS / UMD build. Projects using Webpack or other bundlers used the default import syntax to pull the CommonJS build:

// old way
import XLSX from "xlsx";

v0.18.1 activated the ESM build for common tooling. See https://docs.sheetjs.com/docs/installation/frameworks for more details. The literal equivalent of the old import is

// new way
import * as XLSX from "xlsx";
import * as cptable from 'xlsx/dist/cpexcel.full.mjs';
XLSX.set_cptable(cptable);

Tree Shaking is supported with the ESM build!. If a project is only exporting XLSX files (using utils and writeFile), using named imports with writeFileXLSX drastically reduces bundle size:

import { utils, writeFile } from "xlsx";

---

Sheet.js is providing the following warning in the Angular CLI for the new v10 release:

Starting with Angular 10 the Angular CLI now provide warnings for CommonJS modules. Read more about it here:
https://blog.angular.io/version-10-of-angular-now-available-78960babd41

When you use a dependency that is packaged with CommonJS, it can result in larger slower applications.
Starting with version 10, we now warn you when your build pulls in one of these bundles. If you’ve started seeing these warnings for your dependencies, let your dependency know that you’d prefer an ECMAScript module (ESM) bundle.

And here:
https://angular.io/guide/build#configuring-commonjs-dependencies

It is recommended that you avoid depending on CommonJS modules in your Angular applications. Depending on CommonJS modules can prevent bundlers and minifiers from optimizing your application, which results in larger bundle sizes. Instead, it is recommended that you use ECMAScript modules in your entire application. For more information, see How CommonJS is making your bundles larger

They reference the following article regarding the issues with CommonJS:
https://web.dev/commonjs-larger-bundles/

Additionally I've seen a few discussions by Angular staff members on Github discussing potentially dropping CommonJS support by default, and making it an opt-in feature in the future.

I realize the Angular team is taking a very strong armed approach here, but their reasoning seems solid. Needless to say I'd love to see ESM support if possible. Thanks!

[SheetJSDev]

CommonJS requires no language changes and thus is compatible with older IE and other environments like PhotoShop extensions. ESM breaks older browsers and legacy environments with the introduction of the new export keyword. While Google and the Angular team may be quick to "move fast and break things", we'd prefer not to.

That said, is there some stopgap measure? Can we create a dummy index.mjs file that imports the standalone packaged dist script? We could also generate a script that just concatenates the dist script with "export default XLSX;"

[endigo9740]

Yep, I understand the goal is wide support, but the stopgap solution you've suggested seems reasonable to me!

[itayperry]

Was this issue solved? I work with Angular as well :)

[srijken]

@SheetJSDev what needs to be done to get any of those two stopgap measures done?

Would it be possible to publish the dist script concatenated with the default export as a separate package or..?

[Leccho]

I beleive you should still have a version with ECMAScript.

[techmaster242]

I'm running into this same issue. The resulting file is very large (725kB) and slow. If we could get this working as an ES module, it would help a lot.

[chacabuk]

Any advance on this?

[sivadinesh1]

Team I get this warning, what should be done? no clear answer

[Leccho]

There's nothing to do as long as they don't update the librairie. It still works tought. It's just a warning to tell you it might take longer to load the app

[jlabanca]

Adding my vote.

As a sort of workaround, you can use lazy loading modules to at least prevent it from being include in the initial download.
https://angular.io/guide/lazy-loading-ngmodules

You need to make sure that any refences to XLSX are isolated to the lazily loaded module. You can use webpack-bundle-analyzer to analyze your app and see what's included in the main.js file.

[SheetJSDev]

The write codecs and utility functions are easy to split, but the read codecs are harder. The whole point of read and readFile is to mask the file format details so it doesn't really make sense to say you only want XLSX read support or only want XLS read support. This is especially important since many third party tools "cheat" by exporting HTML tables or SpreadsheetML 2003 XML with a .xls extension.

It is theoretically possible to modularize as follows:

1. split up each codec into its own module

2. add some helper functions to populate the library with the codecs

3. read / readFile / write / writeFile would only operate with the known codecs.

This would imply end-user code that looks like:

import { read as read_XLSX, write as write_XLSX } from 'xlsx/codecs/xlsx';
import { read as read_XLS } from 'xlsx/codecs/xls';
import { readFile, writeFile, read, write, load_read_codec, load_write_codec } from 'xlsx';

[read_XLSX, read_XLS].forEach(c => load_read_codec(c));
[write_XLSX].forEach(c => load_write_codec(c))

const good_wb = readFile("valid.xlsx"); // assuming valid.xlsx is a valid XLSX file, returns a workbook
try { 
  const bad_wb = readFile("invalid.htm"); // if the HTML codec is not loaded, throw an error
} catch(e) { }

XLSX.writeFile(good_wb, "out.xlsx"); // succeeds since XLSX write codec was loaded
try {
  XLSX.writeFile(good_wb, "out.xls"); // fails since XLS write codec was not loaded
} catch(e) { }

[blondie63]

Hi all, i've same issue on my angular 11 app, is there now a final solution ?