Dual-build for ESM and CJS

[steveluscher]

Summary

In this PR we introduce an ESM build. This should ensure compatibility with ESM build pipelines, including:

• Create React App
• Ember Embroider

…and all of the other ESM-based bundlers that folks have been having trouble with since v8.

This should be released as v9 because of how much change there is.

Changes

• Everything is exported at the top level now, so that devs don't have to rely on the ability to dive into dist/ to pick out one particular module (eg. WebSocketBrowserImpl). More about this, including an example, in API.md. Anything you don't use among the exports should be tree-shaken away by your optimizing compiler (eg. if you only use WebSocket then Client should get tree-shaken away).
• Each export is built into one file. This eliminates the class of problem where bundlers like Embroider had trouble importing dependencies in dist/.
• We bundle with Parcel now, and configure the entire build through package.json
• What gets published to npm now is just dist/, README.md, LICENSE, and package.json

Test plan

Unit tests

npm test

@solana/web3.js

Applied this diff and rebuilt. IIFE bundle worked.

Create React App

1. Created a brand new CRA app

   npm create react-app test-app
   cd test-app
   npm add rpc-websockets@../rpc-websockets
   npm add @solana/web3.js@../solana-web3.js-git/packages/library-legacy
   

2. Added this code to App.js

   import { Connection } from "@solana/web3.js";
   import { Client } from "rpc-websockets";
   
   const ws = new Client("wss://echo.websocket.org");
   ws.on("open", function () {
       console.log("WebSocket Client Connected");
   });
   
   const c = new Connection("https://api.devnet.solana.com");
   c.getLatestBlockhash().then(console.log);
   c.onSlotChange(console.log);
   

   

Next.js with App Router

1. Created a brand new Next.js app

   npm create next-app test-app
   cd test-app
   npm add rpc-websockets@../rpc-websockets
   npm add @solana/web3.js@../solana-web3.js-git/packages/library-legacy
   

2. Added this code to page.tsx

   'use client';
   import { Connection } from "@solana/web3.js";
   import { Client } from "rpc-websockets";
   
   export default function Home() {
       useEffect(() => {
           const ws = new Client("wss://echo.websocket.org");
           ws.on("open", function () {
               console.log("WebSocket Client Connected");
           });
   
           const c = new Connection("https://api.devnet.solana.com");
           c.getLatestBlockhash().then(console.log);
           c.onSlotChange(console.log);
       }, []);
       /* ... */
   };
   

3. Ran npm run dev
   

Next.js with App Router

1. Created a brand new Next.js app with Pages router

   npm create next-app test-app
   cd test-app
   npm add rpc-websockets@../rpc-websockets
   npm add @solana/web3.js@../solana-web3.js-git/packages/library-legacy
   

2. Added this code to _app.tsx

   import { Connection } from "@solana/web3.js";
   import { Client } from "rpc-websockets";
   
   export default function App({ Component, pageProps }: AppProps) {
       useEffect(() => {
           const ws = new Client("wss://echo.websocket.org");
           ws.on("open", function () {
               console.log("WebSocket Client Connected");
           });
   
           const c = new Connection("https://api.devnet.solana.com");
           c.getLatestBlockhash().then(console.log);
           c.onSlotChange(console.log);
       }, []);
       /* ... */
   };
   

3. Ran npm run dev
   

[steveluscher]

This is the complete Parcel configuration. When you run parcel build it reads this data to know how to behave.

[steveluscher]

Downstream clients may actually need these dependencies if they're building for the browser, so I moved them out of devDependencies.

[steveluscher]

Converting to draft for a moment; gotta figure out a way to build a typedef for the browser bundle (ie. it needs to omit Server from the exports)

[steveluscher]

OK, Parcel is not appropriate for this multi-package build (browser, node, iife). I've replaced it with the build pipeline that we use ourselves to build multiple packages, retested it, and added Next.js test plans for both App router and Pages router.

Ready to review.

[steveluscher]

Only used for typechecking now, not for building.

[steveluscher]

When building browser-bundle.js, include the buffer polyfill.

[mkozjak]

Amazing work, @steveluscher! Thanks much.
Tests are passing. I will squash-merge this one now.

[steveluscher]

I hope this fixes everyone’s build issues once and for all. Sorry for the wild ride, everyone. Once this works it should let y’all:

• Import just what you need for smaller bundles
• Build for the exact target you need for smaller bundles
• Work in ESM projects