You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/adr/esm-support.md
+7-6Lines changed: 7 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,7 @@ We have acknowledged the need and discussion around it touched on multiple scena
24
24
- keeping default settings as the main target is on the server
25
25
26
26
**Why do we need this decision?**
27
-
We aimed to consolidate the Technical Committee's (TC) opinion on this topic. It is important to emphasize that Express is an HTTP framework specifically designed for Node.js. Over the years, technology has evolved, and new runtimes have emerged. Additionally, some of our libraries are being utilized by the community in other environments, such as browsers.
27
+
We aimed to consolidate the Technical Committee's (TC) opinion on this topic. It is important to emphasize that Express is an HTTP framework specifically designed for Node.js. Over the years, technology has evolved, and new runtimes have emerged. Additionally, some of our libraries are being utilized by the community in other environments.
28
28
29
29
**What problem does it solve or avoid?**
30
30
Ambiguity and uncertainty for the community, alongside clear guidance for repository maintainers and contributors.
@@ -39,7 +39,7 @@ Ambiguity and uncertainty for the community, alongside clear guidance for reposi
39
39
40
40
During the [working session](https://github.com/expressjs/discussions/issues/320), we had an in-depth discussion about this topic. After careful consideration, we concluded that we will not make a dedicated effort to export our libraries in the ESM format. Instead, we will continue exporting the libraries as we have done historically.
41
41
42
-
This decision is motivated by the lack of resources to maintain such an effort in the long term. It is also worth noting that Express is specifically designed to run with Node.js. While some of our libraries can be considered "isomorphic," this was unintended and can currently be classified as an "unofficial but functional feature." Consequently, our CI systems do not include browsers or other runtimes as part of their testing workflows.
42
+
This decision is motivated by the lack of resources to maintain such an effort in the long term. It is also worth noting that Express was specifically designed to run with Node.js. While some of our libraries can run in other runtimes, this can currently be classified as an "unofficial and untested feature." Consequently, our CI systems do not include other runtimes as part of their testing workflows.
43
43
44
44
At present, our libraries function seamlessly in Node.js, supporting both CommonJS and ESM. Transitioning to support additional scenarios, such as direct ESM exports, would require significant changes to our CI systems and additional maintenance overhead.
45
45
@@ -51,22 +51,22 @@ Future issues can be closed with a link to this document.
51
51
52
52
## Rationale
53
53
54
-
CommonJS is the default syntax in Node.js. While the JavaScript ecosystem has increasingly moved toward ESM due to its compatibility with browsers, enhanced tree-shaking capabilities, and support for dynamic imports, there are still complexities and challenges associated with ESM.
54
+
CommonJS is the default syntax in Node.js. While the JavaScript ecosystem has increasingly moved toward ESM due to its compatibility with browsers, enhanced tree-shaking capabilities (coming from bundler tools), and support for dynamic imports, there are still complexities and challenges associated with ESM.
55
55
56
56
Adopting ESM for our libraries would require a significant investment of time and resources to ensure proper implementation and long-term maintenance. While it is not impossible to achieve, it represents a considerable effort. Moreover, the majority of our users already utilize our libraries in their projects, relying on bundlers to handle the necessary transformations without issues.
57
57
58
58
-**Alternatives Considered:**
59
59
- Alternative 1: Add ESM export to our libraries. CommonJS format is accepted by all most popular bundlers.
60
-
-**Pros and Cons**: Outline the pros and cons of the chosen solution.
61
60
-**Why is this decision the best option?** Time and energy can be shifted to other topics.
62
61
63
62
## Consequences
64
63
65
64
-**Positive Impact**: It does not require to support another set of tools and one more major (or at least big) release.
66
65
-**Negative Impact**:
67
-
- Packages can't be used in deno projects and potentially in other future runtime engines for JavaScript that decide to not support commonjs. That can be a potential user miss
66
+
- No guarantee the packages work in browser environments.
67
+
- Potential community library fork (to make it ESM-friendly) might lack security updates over time
68
68
- OSS library authors that use our packages in ESM native libs might suffer from a lack of support
69
-
-**Mitigations**: Potential decision update to support isomorphism for selected libraries (not specified yet) and exposing both types (CJS and ESM)
69
+
-**Mitigations**: Potential decision update for selected libraries (not specified yet) and exposing both types (CJS and ESM)
70
70
71
71
## References
72
72
@@ -82,3 +82,4 @@ Track changes or updates to this ADR over time. Include the date, author, and a
0 commit comments