Skip to content

Export ESM module #1518

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
flying-sheep wants to merge 11 commits into
base: main
Choose a base branch
from
+309 −5
Open

Export ESM module #1518

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
bf78289
Export ESM module
flying-sheep May 10, 2026
a08010a
whoops
flying-sheep May 10, 2026
4c768a6
ws
flying-sheep May 10, 2026
79bf6b8
explicit types
flying-sheep May 10, 2026
a172be8
preinstall
flying-sheep May 10, 2026
e7ec445
revert
flying-sheep May 10, 2026
d352523
smaller diff
flying-sheep May 10, 2026
32fb71c
undo unrelated changes
flying-sheep May 21, 2026
adedd3c
use renamer
flying-sheep May 21, 2026
297d6b8
overwrite
flying-sheep May 21, 2026
a9c5490
simpler dep
flying-sheep May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
281 changes: 281 additions & 0 deletions api/package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

17 changes: 14 additions & 3 deletions api/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,16 @@
"API",
"Environments"
],
"main": "./out/main.js",
"types": "./out/main.d.ts",
"exports": {
"import": {
"types": "./out/esm/main.d.ts",
"default": "./out/esm/main.mjs"
},
"require": {
"types": "./out/cjs/main.d.ts",
"default": "./out/cjs/main.cjs"
}
},
Comment thread
flying-sheep marked this conversation as resolved.
"engines": {
"node": ">=22.21.1",
"vscode": "^1.110.0"
Expand All @@ -30,12 +38,15 @@
"prepublishOnly": "echo \"⛔ Can only publish from a secure pipeline ⛔\" && node -e \"process.exitCode = 1\"",
"prepack": "npm run all:publish",
"all:publish": "git clean -xfd . && npm install && npm run compile",
"compile": "tsc -b ./tsconfig.json",
"compile": "npm run compile:esm && npm run compile:cjs",
"compile:esm": "tsc -b ./tsconfig.esm.json && mve out/esm/main.js out/esm/main.mjs",
"compile:cjs": "tsc -b ./tsconfig.cjs.json && mve out/cjs/main.js out/cjs/main.cjs",
"clean": "node -e \"const fs = require('fs'); fs.rmSync('./out', { recursive: true, force: true });\""
},
"devDependencies": {
"@types/node": "^22.0.0",
"@types/vscode": "^1.99.0",
"mve": "^0.1.2",
"typescript": "^5.1.3"
}
}
2 changes: 0 additions & 2 deletions api/tsconfig.json → api/tsconfig.base.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,9 @@
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"lib": ["ES2020"],
"declaration": true,
"strict": true,
"outDir": "./out",
"rootDir": "src",
"esModuleInterop": true,
"skipLibCheck": true,
Expand Down
7 changes: 7 additions & 0 deletions api/tsconfig.cjs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"extends": "./tsconfig.base.json",
"compilerOptions": {
"module": "commonjs",
"outDir": "./out/cjs"
}
}
7 changes: 7 additions & 0 deletions api/tsconfig.esm.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"extends": "./tsconfig.base.json",
"compilerOptions": {
"module": "esnext",
Copy link
Copy Markdown
Contributor

@StellaHuang95 StellaHuang95 May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 "module": "esnext" is the wrong target for a package shipped to Node — it's a footgun for future contributors.

esnext emits ESM syntax but does not enforce Node's ESM resolution rules. The most important rule TypeScript skips under esnext is that relative imports must include the file extension:

// Compiles fine under "module": "esnext"
import { thing } from './helper';

// Required by real Node ESM at runtime
import { thing } from './helper.js';

Today this happens to work because main.ts has zero relative imports — the only import is 'vscode'. But the next contributor who splits a helper into a separate file and writes import { x } from './helper' will:

  • Compile cleanly ✅
  • Pass review ✅
  • Get published ✅
  • Crash at runtime in any pure-Node ESM consumer with Cannot find module './helper' ❌

"module": "node16" (or "nodenext") makes TypeScript enforce the .js extension at compile time, catching the bug immediately. It also makes TS emit .mjs files, which — bonus — eliminates the "type": "module" issue I flagged on package.json since the extension itself signals ESM to Node.

Recommend "module": "node16" here.

Copy link
Copy Markdown
Contributor Author

@flying-sheep flying-sheep May 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately that’s not true, typescript only ever creates .js files (and .d.ts files): microsoft/TypeScript#18442 (comment)

To switch to .mjs (and maybe also .cjs), we would need a rename step as described in the linked comment.

Would you prefer that rename step to adding the nested package.json? There is a dedicated tool to do the latter: https://github.com/azu/tsconfig-to-dual-package

I think I’m tending towards using that tool because of the aforementioned footgun about not being allowed to reuse the same .d.ts file.

Copy link
Copy Markdown
Contributor

@StellaHuang95 StellaHuang95 May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not an expert on this, so thanks for pointing this out🙂 My understanding is there are two concerns here.

At build time: tsc doesn't enforce extensions on relative imports under module: "esnext", so it compiles fine but might break at runtime in Node's strict ESM resolver.

Switching tsconfig.esm.json to module: "nodenext" would catch this at compile time, but it also needs "type": "module" added to api/package.json so that tsc detects src/main.ts as an ESM source (otherwise nodenext would emit CJS into the ESM build).

At consume time: the .d.ts file paired with the ESM entrypoint is classified as CJS (since the nearest ancestor package.json has no "type":"module"), mismatching the .mjs file which Node treats as ESM at runtime. The fix would be either:

  • Rename .d.ts → .d.mts/.d.cts (same mve step you already use for .js), or
  • Use tsconfig-to-dual-package to add sentinel package.json files:
  1. out/esm/main.d.ts → walk up → out/esm/package.json ("type":"module")
  2. out/cjs/main.d.ts → walk up → out/cjs/package.json ("type":"commonjs")

Is this what you're thinking too? No preference on which one to pick.

Copy link
Copy Markdown
Contributor Author

@flying-sheep flying-sheep May 22, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, so "module": "nodenext" | "node16" flexibly emit ESM or CJS code based on "type": "module" | "commonjs" in package.json, and it changes the module resolution TypeScript uses when type checking / building.

I think this context-dependent mode would be confusing, and instead opted for the explict "module" values in the tsconfig.<variant>.json files, that result in the following code being emitted:

  • the ESM variant has import { extensions, } from 'vscode';
  • the CJS variant has const vscode_1 = require("vscode"); and then uses vscode_1.extensions.

This looks ideal, so we have build time settled. Regarding consume time, there are two technologies that must be satisfied:

  1. node.js is satisfied if we either use .mjs/.cjs or if we use .js and the closest package.json has the appropriate "type"
  2. TypeScript is satisfied if the resolved file has an associated .d.ts

I forgot to address 1. properly at first, but opted for renaming file suffixes, so we don’t have to use extra package.jsons. Using the current combination of file endings and "imports" map, both technologies should be satisfied explicitly and cleanly:

  • at type check time, users need to configure TypeScript to resolve the node.js package (including its import map), where both import * as api from "@vscode/python-environments" or require("@vscode/python-environments") will lead it to either out/esm/main.d.ts or out/cjs/main.d.ts based on the users’ settings.
  • at build time, the same applies
  • at node.js runtime (or when using a bundler), the same import map will be used to resolve to either out/esm/main.mjs or out/cjs/main.cjs, which node.js will be interpret as the correct module type based on file extension

"outDir": "./out/esm"
}
}
Loading