chore(build): build a universal ESM and CommonJS package #371

gagik · 2025-07-15T11:24:10Z

Adds ESM and CommonJS-based exports to the package.

The motivation is largely to add support for VSCode to use the library.

Possible Alternatives

Target cjs and use gen-esm-wrapper - might be simpler in a sense and more consistent with how we deal with it in i.e. mongosh and other packages. But because we were distributing an ESM package until now, the potential breaking change is a bit worrying.

Inspired by #325

Relevant reading:

…gagik/vitest

…gagik/cjs-target

gagik · 2025-07-15T12:34:46Z

scripts/update-package-info.ts

+const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as PackageJson;
+
+// Define the packageInfo.ts content
+const packageInfoContent = `// This file was generated by scripts/update-package-info.ts - Do not edit it manually.


there's no good way to have __dirname / import.meta.dirname as explored in https://evertpot.com/universal-commonjs-esm-typescript-packages/ and I couldn't think of anything better either. so instead we'll generate the file on-demand. This is similar to how it is done in github.com/mongodb-js/mongosh/

coveralls · 2025-07-15T12:38:49Z

Pull Request Test Coverage Report for Build 16320816887

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

2 of 66 (3.03%) changed or added relevant lines in 6 files are covered.
1 unchanged line in 1 file lost coverage.
Overall coverage decreased (-0.5%) to 76.93%

Changes Missing Coverage	Changed/Added Lines	%
src/lib.ts	3	0.0%
scripts/updatePackageVersion.ts	8	0.0%
scripts/createUniversalPackage.ts	11	0.0%
src/index.ts	42	0.0%

Files with Coverage Reduction	New Missed Lines	%
src/index.ts	1	1.92%

Totals
Change from base Build 16292877152:	-0.5%
Covered Lines:	2827
Relevant Lines:	3635

💛 - Coveralls

gagik · 2025-07-15T12:39:04Z

package.json

  "scripts": {
    "prepare": "npm run build",
    "build:clean": "rm -rf dist",
-    "build:compile": "tsc --project tsconfig.build.json",
+    "build:update-package-info": "tsx scripts/update-package-info.ts",
+    "build:esm": "tsc --project tsconfig.esm.json && echo '{\"type\":\"module\"}' > dist/package.json",


Source: As you can also see that both our cjs and esm packages get a 1-line package.json file with a type property.

This is required because Node needs to know wether files with a .js extensions should be interpreted as CommonJS or ESM. It can’t figure it out after opening it.

Node will look at the nearest package.json to see if the type property was specified.

tsconfig.esm.json

gagik · 2025-07-15T15:41:10Z

.github/workflows/check.yml

@@ -55,4 +55,4 @@ jobs:
          rm -rf node_modules
          npm pkg set scripts.prepare="exit 0"
          npm install --omit=dev
-      - run: npx -y @modelcontextprotocol/inspector --cli --method tools/list -- node dist/index.js --connectionString "mongodb://localhost"


I'm setting to ESM to keep the changes minimal. Doing cjs default won't change our issues with the oidc-plugin, I think the only way to deal with that is to make some changes on the plugin itself to not depend on the require of an ESM module which is a higher Node version feature.

Generally worth checking if we're going to have any problems with dist/index.js going away.

I'd expect the worst being our dev environment configurations no longer being correct.

Otherwise we can also create a index.js alias to point to esm.

I think this is solved, now that you have dist/index.js pointing to esm.

gagik · 2025-07-15T15:44:12Z

src/lib.ts

@@ -0,0 +1,4 @@
+export { Server, type ServerOptions } from "./server.js";
+export { Telemetry } from "./telemetry/telemetry.js";


we can consider exporting a single class which would make the setup easier but I'll leave that to future followups

gagik · 2025-07-16T08:15:14Z

scripts/createUniversalPackage.ts

+
+// Create a dist/index.js file that imports the ESM index.js file
+// To minimize breaking changes from pre-universal package time.
+const indexPath = resolve(distDir, "index.js");


this is just out of precaution in case some of our deployments end up looking for dist/index.js... can be removed though

I personally think its fine to have it.

himanshusinghs

Looks perfect. Tested it locally with vscode and works as expected 🚀

Totally unrelated but you might wanna cherry-pick the changes in this commit because currently we are shipping some unnecessary files in our final dist.

himanshusinghs · 2025-07-16T11:37:17Z

.github/workflows/check.yml

@@ -55,4 +55,4 @@ jobs:
          rm -rf node_modules
          npm pkg set scripts.prepare="exit 0"
          npm install --omit=dev
-      - run: npx -y @modelcontextprotocol/inspector --cli --method tools/list -- node dist/index.js --connectionString "mongodb://localhost"


I think this is solved, now that you have dist/index.js pointing to esm.

.github/workflows/prepare_release.yaml

himanshusinghs · 2025-07-16T11:44:35Z

package.json

+      }
+    }
+  },
+  "main": "./dist/cjs/lib.js",


Perhaps we should add the types as well pointing to "./dist/cjs/lib.d.ts" considering that the main is for older tooling?

himanshusinghs · 2025-07-16T11:45:15Z

scripts/createUniversalPackage.ts

+
+// Create a dist/index.js file that imports the ESM index.js file
+// To minimize breaking changes from pre-universal package time.
+const indexPath = resolve(distDir, "index.js");


I personally think its fine to have it.

gagik added 16 commits July 14, 2025 19:47

chore(tests): switch to vitest

6eed483

fix: remove traces of jest

463b6cc

fix: add and fix vitest linting

3b03327

fix: coverage

2d63956

fix: use --exclude

6e24d64

fix: increase hook timeout

3f10cbd

fix: from feedback

52ccf24

feat: use custom toIncludeSameMembers matcher

cbebf3e

Merge branch 'main' of github.com:mongodb-js/mongodb-mcp-server into …

8fc12bc

…gagik/vitest

fix: remove unneeded globals

3bf00e6

WIP:

c138c1e

wip

2e76d9a

fix: add test, keep backwards compatibility

49dccbe

Merge branch 'main' of github.com:mongodb-js/mongodb-mcp-server into …

a262914

…gagik/cjs-target

fix: update package-lock

5a12fec

fix: less scripts

ad51a41

gagik commented Jul 15, 2025

View reviewed changes

fix: clearer typescript

7064ad0

gagik changed the title ~~WIP ESM-CJS targetting~~ chore(build): build a universal ESM and CommonJS package Jul 15, 2025

fix: add dist/cjs

70cd5c9

gagik commented Jul 15, 2025

View reviewed changes

tsconfig.esm.json Outdated Show resolved Hide resolved

gagik added 7 commits July 15, 2025 14:53

fix: conver to proper file URLs

00a1b19

fix: use arelative

515b7c5

fix: use project root

6f5540e

fix: use esm/lib.js

c61e643

fix: resolve directly

9e4d91b

fix: use a script to ensure windows support

bf35972

fix: use esm as default

c70853e

gagik commented Jul 15, 2025

View reviewed changes

gagik marked this pull request as ready for review July 15, 2025 15:41

gagik requested a review from a team as a code owner July 15, 2025 15:41

gagik commented Jul 15, 2025

View reviewed changes

gagik added 2 commits July 16, 2025 09:22

fix: remove redundant bits

384a3be

fix: add backwards compatibility

6a70bbe

gagik commented Jul 16, 2025

View reviewed changes

himanshusinghs approved these changes Jul 16, 2025

View reviewed changes

gagik and others added 2 commits July 16, 2025 15:18

fix: add types

820292c

chore: package only dist and other req files

cce6ddb

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore(build): build a universal ESM and CommonJS package #371

chore(build): build a universal ESM and CommonJS package #371

Uh oh!

gagik commented Jul 15, 2025 •

edited

Loading

Uh oh!

gagik Jul 15, 2025

Uh oh!

coveralls commented Jul 15, 2025 •

edited

Loading

Uh oh!

gagik Jul 15, 2025

Uh oh!

Uh oh!

gagik Jul 15, 2025

Uh oh!

himanshusinghs Jul 16, 2025

Uh oh!

gagik Jul 15, 2025

Uh oh!

gagik Jul 16, 2025

Uh oh!

himanshusinghs Jul 16, 2025

Uh oh!

himanshusinghs left a comment

Uh oh!

himanshusinghs Jul 16, 2025

Uh oh!

Uh oh!

himanshusinghs Jul 16, 2025

Uh oh!

himanshusinghs Jul 16, 2025

Uh oh!

Uh oh!

		@@ -0,0 +1,4 @@
		export { Server, type ServerOptions } from "./server.js";
		export { Telemetry } from "./telemetry/telemetry.js";

chore(build): build a universal ESM and CommonJS package #371

Are you sure you want to change the base?

chore(build): build a universal ESM and CommonJS package #371

Uh oh!

Conversation

gagik commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Possible Alternatives

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coveralls commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 16320816887

Warning: This coverage report may be inaccurate.

Details

💛 - Coveralls

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

himanshusinghs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gagik commented Jul 15, 2025 •

edited

Loading

coveralls commented Jul 15, 2025 •

edited

Loading