diff --git a/docs/arch/README.md b/docs/arch/README.md index b1c115ee25..e9973486f7 100644 --- a/docs/arch/README.md +++ b/docs/arch/README.md @@ -56,3 +56,4 @@ - [ADR 54: app-root](adr-54.md) - [ADR 55: lib-user](adr-55.md) - [ADR 56: Use markdownz to parse markdown](adr-56.md) +- [ADR 57: build @zooniverse/classifier and @zooniverse/react-components as ES modules](adr-57.md) diff --git a/docs/arch/adr-57.md b/docs/arch/adr-57.md new file mode 100644 index 0000000000..688b60e8ae --- /dev/null +++ b/docs/arch/adr-57.md @@ -0,0 +1,18 @@ +# ADR 57: build @zooniverse/classifier and @zooniverse/react-components as ES modules + +## Status +Accepted + +## Context +The classifier and React components libraries were originally built with Webpack. Each was built as a single large UMD `main.js` file. + +Since the monorepo was first started, ES modules have become the standard for JS packages. Recent versions of Webpack can [tree-shake ESM](https://webpack.js.org/guides/tree-shaking/) to remove unused code. CommonJS is used for legacy package support, and increasingly deprecated for newer packages. All modern browsers, and NodeJS, support `import/export`. + +## Decision +Since [PR 3900](https://github.com/zooniverse/front-end-monorepo/pull/3900), each package is published as ESM, using Babel to transform the JSX source files to JS. A Babel CJS build, transforming `import/export` to `require`, is kept for legacy purposes. + +## Consequences +- Each library has a `build:es6` script and a `build:cjs` script. Over time, the CJS build can be deprecated and removed. +- Each library has two entrypoints: `dist/esm` for ESM, and `dist/cjs` for CommonJS. +- Production builds and deploys only need the `build:es6` script. +- Older libraries (`@zooniverse/async-states`, `@zooniverse/panoptes-js`, `@zooniverse/grommet-theme`) are still published as CommonJS. \ No newline at end of file