From 2667117cbc8da3352436c5c658fb45183e3a8c85 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Wed, 15 Jan 2025 23:06:42 +0100 Subject: [PATCH 01/15] Create isomorphism-support init doc --- docs/adr/isomorphism-support | 71 ++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/adr/isomorphism-support diff --git a/docs/adr/isomorphism-support b/docs/adr/isomorphism-support new file mode 100644 index 0000000..17aa2af --- /dev/null +++ b/docs/adr/isomorphism-support @@ -0,0 +1,71 @@ +# ADR: Not supporting isomorphism and shipping only commonjs + +## Status + +Proposed + +## Submitters + +- @kjugi +- @wesleytodd +- @ctcpip + +## Decision Owners + +- @expressjs/express-tc + +## Context + +Describe the problem, need, or feature request that prompted this decision. Include any relevant background information, constraints, and considerations that were taken into account. + +- **Why do we need this decision?** +- **What problem does it solve or avoid?** +- **Are there any existing issues/discussions/pull requests related to this?** (Include links to relevant GitHub issues, forum threads, or discussion channels.) + +## Decision + +Clearly state the decision that was made. Describe the chosen solution or approach in detail so that others can understand what was decided. + +- **What will be done?** +- **What will not be done?** (If applicable, specify what was explicitly ruled out.) + +## Rationale + +Explain why this decision was made, including a discussion of the alternatives considered and why they were not chosen. + +- **Alternatives Considered:** + - Alternative 1: [Description and reasons for rejection] + - Alternative 2: [Description and reasons for rejection] +- **Pros and Cons**: Outline the pros and cons of the chosen solution. +- **Why is this decision the best option?** (Explain the key factors that influenced this choice.) + +## Consequences + +Describe the positive and negative outcomes of the decision, including any potential risks or technical debt. + +- **Positive Impact**: What benefits does this decision bring to the project? +- **Negative Impact**: What challenges or limitations does this introduce? +- **Mitigations**: How will we address potential drawbacks or issues? + +## Implementation + +(Optional, if relevant) +Outline the steps required to implement the decision. This section is particularly useful if the decision involves a series of actions or a roadmap. + +- **Phase 1**: [Description] +- **Phase 2**: [Description] +- **Estimated Effort**: Provide a rough estimate of time or effort needed. + +## References + +Include any external links, documents, discussions, or research that were referenced during the decision-making process. + +- https://github.com/pillarjs/router/issues/128 +- https://github.com/expressjs/discussions/issues/297 +- https://nodejs.org/api/modules.html#loading-ecmascript-modules-using-require + +## Changelog + +Track changes or updates to this ADR over time. Include the date, author, and a brief description of each change. + +- **[2025-01-15]**: [@kjugi] - document init From cca63112172c1cbce645e66870f4ec34ae555fab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Wed, 15 Jan 2025 23:07:01 +0100 Subject: [PATCH 02/15] update extension for file --- docs/adr/{isomorphism-support => isomorphism-support.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/adr/{isomorphism-support => isomorphism-support.md} (100%) diff --git a/docs/adr/isomorphism-support b/docs/adr/isomorphism-support.md similarity index 100% rename from docs/adr/isomorphism-support rename to docs/adr/isomorphism-support.md From d8c9118c2cb2b199d08e6f88cc0377fc0ccfd9bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Thu, 16 Jan 2025 00:10:01 +0100 Subject: [PATCH 03/15] Add Link to issue --- docs/adr/isomorphism-support.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/adr/isomorphism-support.md b/docs/adr/isomorphism-support.md index 17aa2af..f2d3feb 100644 --- a/docs/adr/isomorphism-support.md +++ b/docs/adr/isomorphism-support.md @@ -62,6 +62,7 @@ Include any external links, documents, discussions, or research that were refere - https://github.com/pillarjs/router/issues/128 - https://github.com/expressjs/discussions/issues/297 +- https://github.com/expressjs/express/discussions/6051 - https://nodejs.org/api/modules.html#loading-ecmascript-modules-using-require ## Changelog From cda116aa0d76e99673209b6bbfec44b7c0ea1a9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Thu, 16 Jan 2025 01:08:42 +0100 Subject: [PATCH 04/15] Add another issue to the list --- docs/adr/isomorphism-support.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/adr/isomorphism-support.md b/docs/adr/isomorphism-support.md index f2d3feb..b5bf06a 100644 --- a/docs/adr/isomorphism-support.md +++ b/docs/adr/isomorphism-support.md @@ -63,6 +63,7 @@ Include any external links, documents, discussions, or research that were refere - https://github.com/pillarjs/router/issues/128 - https://github.com/expressjs/discussions/issues/297 - https://github.com/expressjs/express/discussions/6051 +- https://github.com/jshttp/cookie/issues/211 - https://nodejs.org/api/modules.html#loading-ecmascript-modules-using-require ## Changelog From b8d5a598fc955f2547900f704844504f1118063c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Fri, 17 Jan 2025 00:28:02 +0100 Subject: [PATCH 05/15] Update isomorphism-support.md --- docs/adr/isomorphism-support.md | 64 +++++++++++++++++---------------- 1 file changed, 34 insertions(+), 30 deletions(-) diff --git a/docs/adr/isomorphism-support.md b/docs/adr/isomorphism-support.md index b5bf06a..2ccb1eb 100644 --- a/docs/adr/isomorphism-support.md +++ b/docs/adr/isomorphism-support.md @@ -16,54 +16,58 @@ Proposed ## Context -Describe the problem, need, or feature request that prompted this decision. Include any relevant background information, constraints, and considerations that were taken into account. +The document's objective is to gather all notable comments and thoughts in one place and track potential changes in this topic. We have noticed that it is repeated frequently in many issues from the community and we need to take action. -- **Why do we need this decision?** -- **What problem does it solve or avoid?** -- **Are there any existing issues/discussions/pull requests related to this?** (Include links to relevant GitHub issues, forum threads, or discussion channels.) +Based on the comments in the issues we know that some of you might not feel happy about it. We have acknowledged the need and discussion around it touched on multiple scenarios. Including: +- rethinking the process and exposing both paths for all libraries +- expose both paths for selected libraries +- keeping default settings as the main target is on the server + +**Why do we need this decision?** +- To reduce noise and maintain the ultimate answer for all of the issues. + +**What problem does it solve or avoid?** +- General response to community request. + +**Are there any existing issues/discussions/pull requests related to this?** +- https://github.com/pillarjs/router/issues/128 +- https://github.com/expressjs/discussions/issues/297 +- https://github.com/expressjs/express/discussions/6051 +- https://github.com/jshttp/cookie/issues/211 ## Decision -Clearly state the decision that was made. Describe the chosen solution or approach in detail so that others can understand what was decided. +During [working session](https://github.com/expressjs/discussions/issues/320) we have decided to not revisit, investigate or discuss this topic further. That means ESM exports won't be available for expressjs as well for pillarjs and jshttp packages. -- **What will be done?** -- **What will not be done?** (If applicable, specify what was explicitly ruled out.) +**What will be done?** + +Future issues can be closed with a link to this document. ## Rationale -Explain why this decision was made, including a discussion of the alternatives considered and why they were not chosen. +CommonJS is the default node.js syntax. The JS world moved in the ESM direction as browsers consumed it well, and bundlers could make a tree-shake feature and dynamic imports. There is still a lot of baggage within the ESM itself and the way how we can use it. + +To keep it short it's a whole new chapter to discuss and consider so it could use a lot of time and resources to make it properly. Don't get this wrong - it's not impossible tho! Most of our users will use the package in their project and pass it to the bundler which will produce the right format without any issues. - **Alternatives Considered:** - - Alternative 1: [Description and reasons for rejection] - - Alternative 2: [Description and reasons for rejection] + - Alternative 1: Add ESM export to our libraries. CommonJS format is accepted by all most popular bundlers. - **Pros and Cons**: Outline the pros and cons of the chosen solution. -- **Why is this decision the best option?** (Explain the key factors that influenced this choice.) +- **Why is this decision the best option?** Time and energy can be shifted to other topics. ## Consequences -Describe the positive and negative outcomes of the decision, including any potential risks or technical debt. - -- **Positive Impact**: What benefits does this decision bring to the project? -- **Negative Impact**: What challenges or limitations does this introduce? -- **Mitigations**: How will we address potential drawbacks or issues? - -## Implementation - -(Optional, if relevant) -Outline the steps required to implement the decision. This section is particularly useful if the decision involves a series of actions or a roadmap. - -- **Phase 1**: [Description] -- **Phase 2**: [Description] -- **Estimated Effort**: Provide a rough estimate of time or effort needed. +- **Positive Impact**: It does not require to support another set of tools and one more major (or at least big) release. +- **Negative Impact**: + - 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 + - OSS library authors that use our packages in ESM native libs might suffer from a lack of support +- **Mitigations**: Potential decision update to support isomorphism for selected libraries (not specified yet) and exposing both types (CJS and ESM) ## References -Include any external links, documents, discussions, or research that were referenced during the decision-making process. +Support for commonjs imports in ESM code is available in the node. Described in docs: +- https://nodejs.org/api/esm.html#interoperability-with-commonjs -- https://github.com/pillarjs/router/issues/128 -- https://github.com/expressjs/discussions/issues/297 -- https://github.com/expressjs/express/discussions/6051 -- https://github.com/jshttp/cookie/issues/211 +Support for ESM modules imports in commonjs is available since node v20 behind the experimental flag and node v23 without a flag. Docs: - https://nodejs.org/api/modules.html#loading-ecmascript-modules-using-require ## Changelog From 7fa2531de37d8d68d79be802802596378a3f542d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Fri, 17 Jan 2025 00:29:29 +0100 Subject: [PATCH 06/15] Update isomorphism-support.md --- docs/adr/isomorphism-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/isomorphism-support.md b/docs/adr/isomorphism-support.md index 2ccb1eb..3ed29cd 100644 --- a/docs/adr/isomorphism-support.md +++ b/docs/adr/isomorphism-support.md @@ -1,4 +1,4 @@ -# ADR: Not supporting isomorphism and shipping only commonjs +# ADR: CommonJS only output ## Status From 0f72b278be1eaad51faf2992b3308dc994a519a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Sat, 18 Jan 2025 22:31:00 +0100 Subject: [PATCH 07/15] Update docs/adr/isomorphism-support.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Ulises Gascón --- docs/adr/isomorphism-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/isomorphism-support.md b/docs/adr/isomorphism-support.md index 3ed29cd..5f7b7b0 100644 --- a/docs/adr/isomorphism-support.md +++ b/docs/adr/isomorphism-support.md @@ -1,4 +1,4 @@ -# ADR: CommonJS only output +# ADR: Export the libraries specifically in ESM format ## Status From 8007ef6cefb68e24388a48a7385a9368ff2688cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Sat, 18 Jan 2025 22:32:08 +0100 Subject: [PATCH 08/15] Update docs/adr/isomorphism-support.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Ulises Gascón --- docs/adr/isomorphism-support.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/adr/isomorphism-support.md b/docs/adr/isomorphism-support.md index 5f7b7b0..5ff45e4 100644 --- a/docs/adr/isomorphism-support.md +++ b/docs/adr/isomorphism-support.md @@ -18,9 +18,9 @@ Proposed The document's objective is to gather all notable comments and thoughts in one place and track potential changes in this topic. We have noticed that it is repeated frequently in many issues from the community and we need to take action. -Based on the comments in the issues we know that some of you might not feel happy about it. We have acknowledged the need and discussion around it touched on multiple scenarios. Including: -- rethinking the process and exposing both paths for all libraries -- expose both paths for selected libraries +We have acknowledged the need and discussion around it touched on multiple scenarios. Including: +- rethinking the process and exposing both options (ESM and CommonJS) for all libraries +- expose both options (ESM and CommonJS) for selected libraries - keeping default settings as the main target is on the server **Why do we need this decision?** From ca5dcb0ff7405daa078e611472f5002734ee1e69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Sat, 18 Jan 2025 22:32:48 +0100 Subject: [PATCH 09/15] Update docs/adr/isomorphism-support.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Ulises Gascón --- docs/adr/isomorphism-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/isomorphism-support.md b/docs/adr/isomorphism-support.md index 5ff45e4..10b5ce7 100644 --- a/docs/adr/isomorphism-support.md +++ b/docs/adr/isomorphism-support.md @@ -24,7 +24,7 @@ We have acknowledged the need and discussion around it touched on multiple scena - keeping default settings as the main target is on the server **Why do we need this decision?** -- To reduce noise and maintain the ultimate answer for all of the issues. +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. **What problem does it solve or avoid?** - General response to community request. From 43b0ed810e3481fc852e9ad9c456caa5e65ea463 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Sat, 18 Jan 2025 22:33:10 +0100 Subject: [PATCH 10/15] Update docs/adr/isomorphism-support.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Ulises Gascón --- docs/adr/isomorphism-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/isomorphism-support.md b/docs/adr/isomorphism-support.md index 10b5ce7..c266fc6 100644 --- a/docs/adr/isomorphism-support.md +++ b/docs/adr/isomorphism-support.md @@ -27,7 +27,7 @@ We have acknowledged the need and discussion around it touched on multiple scena 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. **What problem does it solve or avoid?** -- General response to community request. +Ambiguity and uncertainty for the community, alongside clear guidance for repository maintainers and contributors. **Are there any existing issues/discussions/pull requests related to this?** - https://github.com/pillarjs/router/issues/128 From 166e5f8b94bbcbe06244596c356d6024f8996a9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Sat, 18 Jan 2025 22:57:09 +0100 Subject: [PATCH 11/15] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Ulises Gascón --- docs/adr/isomorphism-support.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/adr/isomorphism-support.md b/docs/adr/isomorphism-support.md index c266fc6..02016e7 100644 --- a/docs/adr/isomorphism-support.md +++ b/docs/adr/isomorphism-support.md @@ -45,9 +45,9 @@ Future issues can be closed with a link to this document. ## Rationale -CommonJS is the default node.js syntax. The JS world moved in the ESM direction as browsers consumed it well, and bundlers could make a tree-shake feature and dynamic imports. There is still a lot of baggage within the ESM itself and the way how we can use it. +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. -To keep it short it's a whole new chapter to discuss and consider so it could use a lot of time and resources to make it properly. Don't get this wrong - it's not impossible tho! Most of our users will use the package in their project and pass it to the bundler which will produce the right format without any issues. +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. - **Alternatives Considered:** - Alternative 1: Add ESM export to our libraries. CommonJS format is accepted by all most popular bundlers. From 9fe1075c0a319147f6e74ad634375b4e646ed871 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Sat, 18 Jan 2025 23:02:36 +0100 Subject: [PATCH 12/15] Update isomorphism-support.md --- docs/adr/isomorphism-support.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/adr/isomorphism-support.md b/docs/adr/isomorphism-support.md index 02016e7..5eabaa1 100644 --- a/docs/adr/isomorphism-support.md +++ b/docs/adr/isomorphism-support.md @@ -37,7 +37,13 @@ Ambiguity and uncertainty for the community, alongside clear guidance for reposi ## Decision -During [working session](https://github.com/expressjs/discussions/issues/320) we have decided to not revisit, investigate or discuss this topic further. That means ESM exports won't be available for expressjs as well for pillarjs and jshttp packages. +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. + +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. + +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. + +**TL;DR**: Dedicated ESM exports will not be available for Express.js, PillarJS, or JSHTTP packages. PR with such a change will not be accepted. **What will be done?** @@ -75,3 +81,4 @@ Support for ESM modules imports in commonjs is available since node v20 behind t Track changes or updates to this ADR over time. Include the date, author, and a brief description of each change. - **[2025-01-15]**: [@kjugi] - document init +- **[2025-01-18]**: [@kjugi] - applied code review suggestions From 4ca69bc925f88fbd267eed9659f5aa8ab0e6d9dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Sun, 2 Feb 2025 00:18:38 +0100 Subject: [PATCH 13/15] Update docs/adr/isomorphism-support.md Co-authored-by: Chris de Almeida --- docs/adr/isomorphism-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/isomorphism-support.md b/docs/adr/isomorphism-support.md index 5eabaa1..9f7399d 100644 --- a/docs/adr/isomorphism-support.md +++ b/docs/adr/isomorphism-support.md @@ -43,7 +43,7 @@ This decision is motivated by the lack of resources to maintain such an effort i 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. -**TL;DR**: Dedicated ESM exports will not be available for Express.js, PillarJS, or JSHTTP packages. PR with such a change will not be accepted. +**TL;DR**: Dedicated ESM exports will not be available for [expressjs](https://github.com/expressjs), [pillarjs](https://github.com/pillarjs), or [jshttp](https://github.com/jshttp) packages. PRs with such a change will not be accepted. **What will be done?** From 01d4903db011a372d301558c5ddec86c755a66e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Sun, 2 Feb 2025 00:19:07 +0100 Subject: [PATCH 14/15] Rename isomorphism-support.md to esm-support.md --- docs/adr/{isomorphism-support.md => esm-support.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/adr/{isomorphism-support.md => esm-support.md} (100%) diff --git a/docs/adr/isomorphism-support.md b/docs/adr/esm-support.md similarity index 100% rename from docs/adr/isomorphism-support.md rename to docs/adr/esm-support.md From 68eb3d089b046c0e67cfed20686098a87dc394ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Kud=C5=82a?= <11212541+kjugi@users.noreply.github.com> Date: Sun, 2 Feb 2025 01:07:19 +0100 Subject: [PATCH 15/15] Update esm-support.md --- docs/adr/esm-support.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/adr/esm-support.md b/docs/adr/esm-support.md index 9f7399d..19c61ab 100644 --- a/docs/adr/esm-support.md +++ b/docs/adr/esm-support.md @@ -24,7 +24,7 @@ We have acknowledged the need and discussion around it touched on multiple scena - keeping default settings as the main target is on the server **Why do we need this decision?** -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. +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. **What problem does it solve or avoid?** 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 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. -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. +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. 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. @@ -51,22 +51,22 @@ Future issues can be closed with a link to this document. ## Rationale -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. +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. 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. - **Alternatives Considered:** - Alternative 1: Add ESM export to our libraries. CommonJS format is accepted by all most popular bundlers. -- **Pros and Cons**: Outline the pros and cons of the chosen solution. - **Why is this decision the best option?** Time and energy can be shifted to other topics. ## Consequences - **Positive Impact**: It does not require to support another set of tools and one more major (or at least big) release. - **Negative Impact**: - - 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 + - No guarantee the packages work in browser environments. + - Potential community library fork (to make it ESM-friendly) might lack security updates over time - OSS library authors that use our packages in ESM native libs might suffer from a lack of support -- **Mitigations**: Potential decision update to support isomorphism for selected libraries (not specified yet) and exposing both types (CJS and ESM) +- **Mitigations**: Potential decision update for selected libraries (not specified yet) and exposing both types (CJS and ESM) ## References @@ -82,3 +82,4 @@ Track changes or updates to this ADR over time. Include the date, author, and a - **[2025-01-15]**: [@kjugi] - document init - **[2025-01-18]**: [@kjugi] - applied code review suggestions +- **[2025-02-02]**: [@kjugi] - applied second part of code review suggestions