ES Module Support for Lumos

Motivation

ES module is the modern standard for JavaScript module system. It is supported by all major browsers and Node.js. It is also the default module system for TypeScript. However, Lumos currently only supports CommonJS module system. Supporting ES module will bring the following benefits:

native support for ES module to use the 1k+ very common modules without transpilation in Lumos
work well with code splitting and tree shaking
- import only the required code
- improve the cold start time
avoid users using non-exported APIs
- the exports field in package.json to specify the entry point of the package

How to

To keep the backward compatibility, we will keep the CommonJS module system as the default, thanks to the conditional exports feature in Node.js, we'll use the exports field in package.json to specify the entry point of the package.

graph TD
    bi-->base;
    codec-->base;
    toolkit-->base;
    base-->ckb-indexer;
    bi-->ckb-indexer;
    codec-->ckb-indexer;
    rpc-->ckb-indexer;
    toolkit-->ckb-indexer;
    testkit-->ckb-indexer;
    bi-->codec;
    base-->common-scripts;
    bi-->common-scripts;
    codec-->common-scripts;
    config-manager-->common-scripts;
    helpers-->common-scripts;
    rpc-->common-scripts;
    toolkit-->common-scripts;
    debugger-->common-scripts;
    hd-->common-scripts;
    base-->config-manager;
    bi-->config-manager;
    codec-->config-manager;
    base-->debugger;
    bi-->debugger;
    codec-->debugger;
    config-manager-->debugger;
    helpers-->debugger;
    rpc-->debugger;
    common-scripts-->debugger;
    experiment-tx-assembler-->debugger;
    hd-->debugger;
    base-->e2e-test;
    bi-->e2e-test;
    ckb-indexer-->e2e-test;
    codec-->e2e-test;
    common-scripts-->e2e-test;
    config-manager-->e2e-test;
    hd-->e2e-test;
    helpers-->e2e-test;
    light-client-->e2e-test;
    rpc-->e2e-test;
    runner-->e2e-test;
    toolkit-->e2e-test;
    utils-->e2e-test;
    testkit-->e2e-test;
    base-->experiment-tx-assembler;
    bi-->experiment-tx-assembler;
    config-manager-->experiment-tx-assembler;
    helpers-->experiment-tx-assembler;
    toolkit-->experiment-tx-assembler;
    base-->hd;
    bi-->hd;
    codec-->hd;
    crypto-->hd;
    base-->hd-cache;
    bi-->hd-cache;
    ckb-indexer-->hd-cache;
    config-manager-->hd-cache;
    hd-->hd-cache;
    rpc-->hd-cache;
    base-->helpers;
    bi-->helpers;
    codec-->helpers;
    config-manager-->helpers;
    toolkit-->helpers;
    base-->light-client;
    ckb-indexer-->light-client;
    rpc-->light-client;
    testkit-->light-client;
    base-->lumos;
    bi-->lumos;
    ckb-indexer-->lumos;
    common-scripts-->lumos;
    config-manager-->lumos;
    hd-->lumos;
    helpers-->lumos;
    rpc-->lumos;
    toolkit-->lumos;
    bi-->molecule;
    codec-->molecule;
    base-->molecule;
    base-->rpc;
    bi-->rpc;
    utils-->runner;
    base-->testkit;
    bi-->testkit;
    codec-->testkit;
    base-->transaction-manager;
    codec-->transaction-manager;
    ckb-indexer-->transaction-manager;
    rpc-->transaction-manager;
    toolkit-->transaction-manager;

[x] Add a build script to build both CJS and ESM output
[x] @ckb-lumos/bi
[x] @ckb-lumos/codec
[x] @ckb-lumos/toolkit
[x] @ckb-lumos/base
[x] @ckb-lumos/rpc
[ ] @ckb-lumos/crypto
[ ] @ckb-lumos/config-manager
[ ] @ckb-lumos/helpers
[ ] @ckb-lumos/hd
[ ] @ckb-lumos/ckb-indexer
[ ] @ckb-lumos/light-client
[ ] @ckb-lumos/transaction-manager
[ ] @ckb-lumos/common-scripts
[ ] Re-design the @ckb-lumos/lumos package
[ ] Documentation
- [ ] Migration guide
[ ] Release and announcement

Breaking

Importing the non-exported API like import {} from '@ckb-lumos/base/lib/...' will be broken

Notes for Contributors

`/#PURE/` annotation for tree shaking

how to

replace the build script with lumos-build --esm --cjs --types
replace the @ckb-lumos/[moduleName]/lib/[subModule] with @ckb-lumos/[moduleName]/[subModule]
add exports and module field to related package.json
add test case in playground/module.test.mjs

ckb-js / lumos