Migrate packages to ESM #2061

connor-baer · 2023-04-24T13:39:00Z

Purpose

While testing out #2020, I discovered that some required dependencies are full ESM packages. ESM cannot be imported into CJS, so we need to migrate Circuit UI to ESM to be able to use web components. This migration is inevitable anyway, and the ecosystem seems ready enough at this point (especially after #2053).

Sindre Sorhus has published an extremely helpful guide for pure ESM packages which I referenced throughout the migration.

Note:
The changes below affect the @sumup/circuit-ui, @sumup/design-tokens, and @sumup/icons packages. @sumup/eslint-plugin-circuit-ui has to remain CJS until ESLint adds support for ESM plugins (see eslint/eslint#15453). I haven't tested if @sumup/cna-template can be turned into a module.

Approach and changes

Module resolution: ESM requires imports to use the full path to a file, including the file name (even for index files) and the file extension. I used eslint-plugin-node's file-extension-in-import rule, global search-and-replace with complex regexes, and lots of sweat and tears to modify all imports. Changed imports make up the vast majority of the diff.
package.json fields:
- Added "type": "module" to all packages:
  
  A package.json "type" value of "module" tells Node.js to interpret .js files within that package as using ES module syntax.
- Switched to the "exports" field to configure the package entry point(s):
  
  The "exports" provides a modern alternative to "main" allowing multiple entry points to be defined, conditional entry resolution support between environments, and preventing any other entry points besides those defined in "exports".
- Configured the "engines" field to require Node.js 16+, the first maintained version of Node with support for ES modules.
Dependencies: CJS dependencies with default exports aren't compatible with ESM out of the box. I resolved to copying the code of the use-previous and use-latest dependencies into the repository and to proxying the default exports of the @emotion/styled and @emotion/is-prop-valid packages.
Storybook + Vite: I replaced Webpack with Vite as Storybook's bundler. This gives us ESM support out of the box and allows us to remove Babel entirely.
Other changes:
- I replaced ts-node with tsx.
- I fixed some dependency cycles that were flagged after adding the eslint-import-resolver-typescript plugin.

Definition of done

changeset-bot · 2023-04-24T13:39:03Z

🦋 Changeset detected

Latest commit: df9d81f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@sumup/design-tokens	Major
@sumup/circuit-ui	Major
@sumup/icons	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2023-04-24T13:39:06Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
oss-circuit-ui	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 27, 2023 3:20pm

codecov · 2023-04-25T09:31:17Z

Codecov Report

Merging #2061 (df9d81f) into next (8adb8fe) will increase coverage by 0.15%.
The diff coverage is 99.40%.

@@            Coverage Diff             @@
##             next    #2061      +/-   ##
==========================================
+ Coverage   96.81%   96.96%   +0.15%     
==========================================
  Files         248      258      +10     
  Lines       22383    23165     +782     
  Branches     2117     2166      +49     
==========================================
+ Hits        21669    22462     +793     
+ Misses        703      697       -6     
+ Partials       11        6       -5

Impacted Files	Coverage Δ
...t-ui/components/Calendar/RangePickerController.tsx	`51.42% <0.00%> (ø)`
...mponents/CalendarTagTwoStep/CalendarTagTwoStep.tsx	`51.03% <80.00%> (-1.04%)`	⬇️
...cuit-ui/components/SelectorGroup/SelectorGroup.tsx	`94.76% <80.00%> (-0.53%)`	⬇️
packages/circuit-ui/components/Anchor/Anchor.tsx	`100.00% <100.00%> (ø)`
.../circuit-ui/components/AspectRatio/AspectRatio.tsx	`100.00% <100.00%> (ø)`
...ackages/circuit-ui/components/AspectRatio/index.ts	`100.00% <100.00%> (ø)`
packages/circuit-ui/components/Avatar/Avatar.tsx	`92.30% <100.00%> (-0.55%)`	⬇️
packages/circuit-ui/components/Avatar/index.ts	`100.00% <100.00%> (ø)`
packages/circuit-ui/components/Badge/Badge.tsx	`100.00% <100.00%> (ø)`
packages/circuit-ui/components/Badge/index.ts	`100.00% <100.00%> (ø)`
... and 125 more

... and 25 files with indirect coverage changes

connor-baer · 2023-04-26T19:32:30Z

packages/circuit-ui/styles/styled.ts

 import { Theme } from '@sumup/design-tokens';

+// eslint-disable-next-line
+const styled = (_styled.default || _styled) as CreateStyled;


This hack is necessary to make Emotion.js' default exports play nice with ESM. Adapted from emotion-js/emotion#2730 (comment).

Thanks for the ref and the comment! Hopefully we can remove this in the future, when Emotion improves ESM support (or when we drop Emotion)

Likely the second 🤞

robinmetral

Not gonna lie, I very much skimmed through this and might have missed things (a lot of file import diff, like you said. GitHub should allow using regex to show/hide diff)

This is such an amazing cleanup of old deps that were sticking around, though! Babel! Lodash! ✨ ⭐ 🌟 💫

Side note: I'm getting mildly panicked with the scope of v7, but maybe that's just me? It's going to be a biggie and we might want to think about ways to help consumer apps opt into as many changes as possible. The build changes to support v7 only (ESM, web components if this makes it into v7, etc) are already going to be a big deal depending on the consumer app stack, so let's try to make everything else as easy to adopt as possible 🙂

(PS. "Comment" not "Approve" primarily because I'm wondering about tests for the hooks that moved to the repo.)

.changeset/flat-lamps-glow.md

babel.config.json

package.json

packages/circuit-ui/hooks/useLatest/useLatest.ts

packages/circuit-ui/package.json

robinmetral · 2023-04-27T14:04:29Z

packages/circuit-ui/styles/styled.ts

 import { Theme } from '@sumup/design-tokens';

+// eslint-disable-next-line
+const styled = (_styled.default || _styled) as CreateStyled;


Thanks for the ref and the comment! Hopefully we can remove this in the future, when Emotion improves ESM support (or when we drop Emotion)

packages/circuit-ui/tsconfig.build.json

packages/icons/package.json

connor-baer · 2023-04-27T15:26:25Z

I'm getting mildly panicked with the scope of v7, but maybe that's just me?

It's true that v7 contains many big infrastructure changes. However, the changes in userland should be minimal. Next.js supports ESM out of the box, Jest can be configured with a single line of code to support ESM dependencies.

The other big change to the implementation will be the switch to Linaria, which will only require the global import of a single stylesheet.

Web components will likely be introduced in v7.x as an experiment and will be fully opt-in.

Or perhaps I misunderstood and you're worried about potential bugs, not the work to upgrade?

tareqlol

Nice!

robinmetral

I'm relieved! Thank you 😌 (and thanks for the new unit test for the hooks!)

github-actions bot added 🗂 icons 🗂 design-tokens labels Apr 24, 2023

vercel bot had a problem deploying to Preview April 24, 2023 13:39 Failure

github-actions bot added the 🗂 circuit-ui label Apr 24, 2023

vercel bot had a problem deploying to Preview April 24, 2023 15:16 Failure

vercel bot had a problem deploying to Preview April 24, 2023 15:28 Failure

vercel bot had a problem deploying to Preview April 24, 2023 19:12 Failure

connor-baer force-pushed the feature/esm branch from 7eac9f2 to 68138ed Compare April 25, 2023 09:21

vercel bot had a problem deploying to Preview April 25, 2023 09:22 Failure

connor-baer mentioned this pull request Apr 26, 2023

Migrate remaining components to TypeScript #2065

Merged

5 tasks

connor-baer force-pushed the feature/esm branch from 68138ed to 233aab5 Compare April 26, 2023 11:25

connor-baer changed the base branch from next to typescript-all-the-things April 26, 2023 11:26

vercel bot deployed to Preview April 26, 2023 11:28 View deployment

connor-baer force-pushed the feature/esm branch from 233aab5 to b53895b Compare April 26, 2023 12:06

vercel bot deployed to Preview April 26, 2023 12:08 View deployment

Base automatically changed from typescript-all-the-things to next April 26, 2023 17:20

connor-baer added 11 commits April 26, 2023 19:23

Replace ts-node with tsx

d6f9b9d

Migrate @sumup/icons to ESM

05a83a3

Switch @sumup/icons to package exports

6b53ea6

Migrate @sumup/design-tokens to ESM

78bbb45

Configure @sumup/circuit-ui as a module

3df3537

Add file extensions using eslint-plugin-node

f7d75d3

Add extensions to component index files

5ed2a80

Search and insert file extensions

13abb54

Proxy isPropValid import

11f9f11

Fix Storybook imports

c211966

Fix css prop types

c875bb9

connor-baer added 2 commits April 26, 2023 19:23

Remove Babel

2d0e54d

Integrate Vite with Turbosnap

74db9e2

connor-baer force-pushed the feature/esm branch from b53895b to 74db9e2 Compare April 26, 2023 17:24

vercel bot deployed to Preview April 26, 2023 17:27 View deployment

connor-baer added 2 commits April 26, 2023 21:26

Re-add exports after rebase

71bc2f1

Add code comments for Emotion workaround

895e68f

connor-baer commented Apr 26, 2023

View reviewed changes

vercel bot deployed to Preview April 26, 2023 19:34 View deployment

connor-baer added 2 commits April 27, 2023 09:56

Add changesets

8205c2c

Raise the minimum Node.js version to 16+

f1f5a71

vercel bot deployed to Preview April 27, 2023 07:58 View deployment

connor-baer marked this pull request as ready for review April 27, 2023 08:09

connor-baer requested a review from a team as a code owner April 27, 2023 08:09

connor-baer requested review from tareqlol and robinmetral and removed request for a team April 27, 2023 08:09

robinmetral reviewed Apr 27, 2023

View reviewed changes

Add unit tests for useLatest and usePrevious

df9d81f

vercel bot deployed to Preview April 27, 2023 15:20 View deployment

connor-baer requested a review from robinmetral April 27, 2023 15:26

tareqlol approved these changes Apr 28, 2023

View reviewed changes

robinmetral approved these changes Apr 29, 2023

View reviewed changes

connor-baer merged commit bc88242 into next Apr 29, 2023

connor-baer deleted the feature/esm branch April 29, 2023 21:33

This was referenced Apr 29, 2023

Version Packages (next) #2069

Merged

Add file extension to react-dates import #2079

Merged

Fix types resolution #2084

Merged

This was referenced Aug 8, 2023

Version Packages #2210

Closed

Version Packages #2213

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate packages to ESM #2061

Migrate packages to ESM #2061

connor-baer commented Apr 24, 2023 •

edited

Loading

changeset-bot bot commented Apr 24, 2023 •

edited

Loading

vercel bot commented Apr 24, 2023 •

edited

Loading

codecov bot commented Apr 25, 2023 •

edited

Loading

connor-baer Apr 26, 2023

robinmetral Apr 27, 2023

connor-baer Apr 27, 2023

robinmetral left a comment

robinmetral Apr 27, 2023

connor-baer commented Apr 27, 2023 •

edited

Loading

tareqlol left a comment

robinmetral left a comment

Migrate packages to ESM #2061

Migrate packages to ESM #2061

Conversation

connor-baer commented Apr 24, 2023 • edited Loading

Purpose

Approach and changes

Definition of done

changeset-bot bot commented Apr 24, 2023 • edited Loading

🦋 Changeset detected

vercel bot commented Apr 24, 2023 • edited Loading

codecov bot commented Apr 25, 2023 • edited Loading

Codecov Report

connor-baer Apr 26, 2023

Choose a reason for hiding this comment

robinmetral Apr 27, 2023

Choose a reason for hiding this comment

connor-baer Apr 27, 2023

Choose a reason for hiding this comment

robinmetral left a comment

Choose a reason for hiding this comment

robinmetral Apr 27, 2023

Choose a reason for hiding this comment

connor-baer commented Apr 27, 2023 • edited Loading

tareqlol left a comment

Choose a reason for hiding this comment

robinmetral left a comment

Choose a reason for hiding this comment

connor-baer commented Apr 24, 2023 •

edited

Loading

changeset-bot bot commented Apr 24, 2023 •

edited

Loading

vercel bot commented Apr 24, 2023 •

edited

Loading

codecov bot commented Apr 25, 2023 •

edited

Loading

connor-baer commented Apr 27, 2023 •

edited

Loading