Skip to content

Commit 68eb3d0

Browse files
authored
Update esm-support.md
1 parent 01d4903 commit 68eb3d0

1 file changed

Lines changed: 7 additions & 6 deletions

File tree

docs/adr/esm-support.md

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ We have acknowledged the need and discussion around it touched on multiple scena
2424
- keeping default settings as the main target is on the server
2525

2626
**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.
2828

2929
**What problem does it solve or avoid?**
3030
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
3939

4040
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.
4141

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.
4343

4444
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.
4545

@@ -51,22 +51,22 @@ Future issues can be closed with a link to this document.
5151

5252
## Rationale
5353

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.
5555

5656
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.
5757

5858
- **Alternatives Considered:**
5959
- 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.
6160
- **Why is this decision the best option?** Time and energy can be shifted to other topics.
6261

6362
## Consequences
6463

6564
- **Positive Impact**: It does not require to support another set of tools and one more major (or at least big) release.
6665
- **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
6868
- 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)
7070

7171
## References
7272

@@ -82,3 +82,4 @@ Track changes or updates to this ADR over time. Include the date, author, and a
8282

8383
- **[2025-01-15]**: [@kjugi] - document init
8484
- **[2025-01-18]**: [@kjugi] - applied code review suggestions
85+
- **[2025-02-02]**: [@kjugi] - applied second part of code review suggestions

0 commit comments

Comments
 (0)