Convert to ESM (#3860)

* Convert extension to ESM and improve Prettier module loading

This PR converts the extension from CommonJS to ESM modules and improves
how Prettier is loaded and resolved.

Key changes:

**ESM Conversion**
- Convert all source files to use ESM imports/exports
- Update esbuild configuration for ESM output
- Add .js extensions to all relative imports
- Update tsconfig for ESM module resolution

**Prettier Module Loading**
- Lazy-load bundled Prettier using dynamic import() for faster activation
- Remove worker thread implementation (PrettierWorkerInstance) - now use
  PrettierDynamicInstance which loads Prettier dynamically
- Improve plugin loading to resolve and import plugins as ES modules
- Add utility functions for finding modules (find-up, resolve-module-entry)

**Extension Activation**
- Make activate() async and await formatter registration
- Ensures formatters are ready when extension.isActive becomes true
- Fixes race condition where tests could run before formatters registered

**Test Infrastructure**
- Add ensureExtensionActivated() helper for reliable test setup
- Extract common format test utilities to formatTestUtils.ts
- Update test imports for ESM compatibility

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Add test for ESM config with plugin import statements

Tests loading plugins via ESM import in prettier.config.mts files,
which is a new feature in Prettier 3.5.0+.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Formatting

* Update readme migraiton warning to remove github admonition

* Simplify resolveModuleEntry to use Node's built-in resolution

Replace manual package.json parsing with createRequire().resolve()
which handles all the complexity of exports, main fields, and fallbacks.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Rename module resolver files with platform suffix

- Rename ModuleResolver.ts → ModuleResolverNode.ts (desktop)
- Rename BrowserModuleResolver.ts → ModuleResolverWeb.ts (browser)
- Keep class export name as ModuleResolver for simplicity
- Update esbuild browser alias plugin for new file names
- Update documentation to reflect new file naming convention

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix resolveModuleEntry to resolve from module's directory

Create the require function from within the target module's directory
so Node's resolution works correctly for local Prettier installations.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Simplify plugin loading: pass paths to Prettier instead of pre-loading

- Fix scoped package resolution in resolveModuleEntry (e.g., @prettier/plugin-xml)
- Simplify plugin loading to just resolve paths and let Prettier import them
- Update browser languages script to dynamically get plugin list from prettier exports

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Read package name from package.json instead of parsing path

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Simplify plugin resolution to match Prettier CLI behavior

- Handle URLs, absolute paths, relative paths, and package names
- Use createRequire to resolve packages from file's directory
- Remove unused findUp import

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix plugin loading for Prettier v2 and improve module resolution

- Use require.resolve with createRequire from target directory
- Only convert plugin paths to file:// URLs for Prettier v3+
- For Prettier v2, pass absolute paths that require() can handle

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: ntotten

.claude/agents/vscode-test-writer.md

@@ -45,38 +45,35 @@ When writing tests, you will:
 
 For this VS Code extension project:
 
-- Tests live alongside source in a test directory structure
+- Tests live in `src/test/suite/` directory
 - Test fixtures are in `test-fixtures/` with their own package.json files
-- Tests run via `yarn test` or the VS Code Debug launcher "Launch Tests"
-- The extension uses webpack bundling, but tests run against unbundled source
-- Key components to test: `PrettierEditService`, `ModuleResolver`, formatting providers
+- Tests run via `npm test` or the VS Code Debug launcher "Launch Tests"
+- The extension uses esbuild bundling with ESM modules
+- Key components to test: `PrettierEditService`, `ModuleResolver`, `PrettierDynamicInstance`
+- Use `ensureExtensionActivated()` from `testUtils.js` to ensure extension is ready before tests
 
 ## Test File Structure
 
 ```typescript
 import * as assert from "assert";
 import * as vscode from "vscode";
-import * as sinon from "sinon";
+import { ensureExtensionActivated } from "./testUtils.js"; // Note: .js extension for ESM
 
-suite("ComponentName Test Suite", () => {
-  let sandbox: sinon.SinonSandbox;
-
-  setup(() => {
-    sandbox = sinon.createSandbox();
-  });
-
-  teardown(() => {
-    sandbox.restore();
+describe("ComponentName Test Suite", () => {
+  before(async () => {
+    await ensureExtensionActivated();
   });
 
-  test("should describe expected behavior", async () => {
+  it("should describe expected behavior", async () => {
     // Arrange
     // Act
     // Assert
   });
 });
 ```
 
+**Note**: This project uses ESM modules. Always use `.js` extension for local imports.
+
 ## Quality Standards
 
 - Tests must be deterministic and not flaky

.claude/settings.json

@@ -1,11 +1,14 @@
 {
   "permissions": {
     "allow": [
-      "WebFetch(domain:prettier.io)",
-      "WebFetch(domain:code.visualstudio.com)",
-      "Bash(npm run prettier:*)",
+      "Bash(npm run check-types:*)",
+      "Bash(npm run compile:*)",
       "Bash(npm run lint:*)",
-      "mcp__ide__getDiagnostics"
+      "Bash(npm run prettier:*)",
+      "Bash(npm test:*)",
+      "mcp__ide__getDiagnostics",
+      "WebFetch(domain:code.visualstudio.com)",
+      "WebFetch(domain:prettier.io)"
     ],
     "deny": [],
     "ask": []

.github/copilot-instructions.md

@@ -16,14 +16,16 @@ This is the official Prettier VS Code extension (`prettier.prettier-vscode`). It
 Entry points:
 
 - Desktop: `src/extension.ts` → bundled to `dist/extension.js`
-- Browser: Same entry, bundled to `dist/web-extension.js` (uses `BrowserModuleResolver` instead of `ModuleResolver`)
+- Browser: Same entry, bundled to `dist/web-extension.cjs` (esbuild swaps `ModuleResolverNode.ts` → `ModuleResolverWeb.ts`)
 
 Core components:
 
-- `src/extension.ts` - Extension activation, creates ModuleResolver, PrettierEditService, and StatusBar
+- `src/extension.ts` - Extension activation (async), creates ModuleResolver, PrettierEditService, and StatusBar
 - `src/PrettierEditService.ts` - Registers VS Code document formatting providers, handles format requests
-- `src/ModuleResolver.ts` - Resolves local/global Prettier installations, falls back to bundled Prettier
-- `src/PrettierInstance.ts` - Interface for Prettier loading, with `PrettierMainThreadInstance` and `PrettierWorkerInstance` implementations
+- `src/ModuleResolverNode.ts` - Resolves local/global Prettier installations, falls back to bundled Prettier (desktop)
+- `src/ModuleResolverWeb.ts` - Uses bundled standalone Prettier for browser (web)
+- `src/PrettierDynamicInstance.ts` - Implements `PrettierInstance` interface, loads Prettier dynamically using ESM `import()`
+- `src/types.ts` - TypeScript types including `PrettierInstance` interface
 
 esbuild produces two bundles:
 
@@ -69,11 +71,11 @@ When reviewing pull requests, focus on:
 ### Performance
 
 - Avoid blocking the extension host main thread
-- `PrettierWorkerInstance` runs Prettier in a worker thread to avoid blocking
+- Prettier is loaded lazily using dynamic `import()` to minimize startup time
 - Module and config resolution results are cached appropriately
 
 ### Browser Compatibility
 
 - Code in the main bundle should work in both Node.js and browser contexts
-- Browser-specific code uses `BrowserModuleResolver`
+- Browser build swaps `ModuleResolverNode.ts` → `ModuleResolverWeb.ts` via esbuild aliasing
 - No Node.js-only APIs in shared code paths

.github/instructions/tests.instructions.md

@@ -8,9 +8,10 @@ Tests run inside a VS Code Extension Development Host using Mocha.
 
 ## Test Structure
 
-- Use Mocha's `suite()` and `test()` functions
+- Use Mocha's `describe()` and `it()` functions (BDD style)
 - Import assertions from `assert` module
 - Tests interact with real VS Code APIs
+- Use `.js` extension for local imports (ESM compatibility)
 
 ## Test Fixtures
 
@@ -28,8 +29,6 @@ Tests run inside a VS Code Extension Development Host using Mocha.
 ## Async Patterns
 
 - Tests are async - use `async/await`
-- Use `wait()` helper when needing delays
-- Prettier v3 formatting is async, may need retries for timing
 
 ## Test File Naming
 

.github/instructions/typescript.instructions.md

@@ -11,6 +11,7 @@ This is a VS Code extension. Follow these patterns:
 - Import VS Code API from `vscode` module: `import { commands, workspace, window } from "vscode"`
 - Use named imports, not namespace imports
 - Group imports: vscode first, then node modules, then local modules
+- **ESM**: Always use `.js` extension for local imports (e.g., `import { foo } from "./utils.js"`)
 
 ## VS Code Extension Patterns
 
@@ -22,13 +23,13 @@ This is a VS Code extension. Follow these patterns:
 ## Class Patterns
 
 - Services follow dependency injection pattern (pass dependencies via constructor)
-- Key services: `LoggingService`, `ModuleResolver`, `PrettierEditService`, `StatusBar`
+- Key services: `LoggingService`, `ModuleResolver` (from `ModuleResolverNode.ts`/`ModuleResolverWeb.ts`), `PrettierEditService`, `StatusBar`
 - Use `Disposable` interface for cleanup
 
 ## Prettier Integration
 
-- Support both Prettier v2 and v3+ via `PrettierInstance` interface
-- `PrettierMainThreadInstance` loads directly, `PrettierWorkerInstance` uses worker thread
+- Support both Prettier v2 and v3+ via `PrettierInstance` interface (defined in `src/types.ts`)
+- `PrettierDynamicInstance` loads Prettier using dynamic ESM `import()` for lazy loading
 - Module resolution: local install → global install → bundled Prettier
 - Handle `.prettierrc`, `.prettierignore`, and `package.json` prettier config
 

.vscode-test.mjs

@@ -1,7 +1,7 @@
 import { defineConfig } from "@vscode/test-cli";
 
 export default defineConfig({
-  files: "out/test/suite/**/*.test.js",
+  files: "out/test/suite/**/*.test.cjs",
   mocha: {
     ui: "bdd",
     timeout: 10000,

.vscode/launch.json

@@ -15,7 +15,7 @@
         "--extensionDevelopmentPath=${workspaceFolder}"
       ],
       "outFiles": ["${workspaceFolder}/dist/**/*.js"],
-      "preLaunchTask": "npm: webpack"
+      "preLaunchTask": "npm: compile"
     },
     {
       "name": "Run Extension (With Other Extensions)",
@@ -24,33 +24,27 @@
       "runtimeExecutable": "${execPath}",
       "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
       "outFiles": ["${workspaceFolder}/dist/**/*.js"],
-      "preLaunchTask": "npm: webpack"
+      "preLaunchTask": "npm: compile"
     },
     {
       "name": "Extension Tests",
       "type": "extensionHost",
       "request": "launch",
-      "runtimeExecutable": "${execPath}",
-      "args": [
-        "${workspaceFolder}/test-fixtures/test.code-workspace",
-        "--disable-extensions",
-        "--extensionDevelopmentPath=${workspaceFolder}",
-        "--extensionTestsPath=${workspaceFolder}/out/test/suite/index"
-      ],
-      "outFiles": ["${workspaceFolder}/out/test/**/*.js"],
+      "testConfiguration": "${workspaceFolder}/.vscode-test.mjs",
+      "outFiles": ["${workspaceFolder}/out/test/**/*.cjs"],
       "preLaunchTask": "npm: compile:test"
     },
     {
       "name": "Run Web Extension",
-      "type": "pwa-extensionHost",
+      "type": "extensionHost",
       "debugWebWorkerHost": true,
       "request": "launch",
       "args": [
         "--extensionDevelopmentPath=${workspaceFolder}",
         "--extensionDevelopmentKind=web"
       ],
       "outFiles": ["${workspaceFolder}/dist/**/*.js"],
-      "preLaunchTask": "npm: webpack"
+      "preLaunchTask": "npm: compile"
     }
   ]
 }

.vscode/tasks.json

@@ -49,13 +49,22 @@
       }
     },
     {
-      "label": "compile",
+      "label": "npm: compile",
       "type": "npm",
       "script": "compile",
       "problemMatcher": "$tsc",
       "presentation": {
         "reveal": "silent"
       }
+    },
+    {
+      "label": "npm: compile:test",
+      "type": "npm",
+      "script": "compile:test",
+      "problemMatcher": "$tsc",
+      "presentation": {
+        "reveal": "silent"
+      }
     }
   ]
 }

CLAUDE.md

@@ -63,7 +63,7 @@ Web tests are located in `src/test/web/suite/` and test the extension's browser
 ### Entry Points
 
 - **Desktop**: `src/extension.ts` → bundled to `dist/extension.js`
-- **Browser**: Same entry, bundled to `dist/web-extension.js` (uses `BrowserModuleResolver` instead of `ModuleResolver`)
+- **Browser**: Same entry, bundled to `dist/web-extension.cjs` (esbuild swaps `ModuleResolverNode.ts` → `ModuleResolverWeb.ts`)
 
 ### Core Components
 
@@ -79,28 +79,25 @@ Web tests are located in `src/test/web/suite/` and test the extension's browser
 - Watches for config file changes (`.prettierrc`, `package.json`, etc.)
 - Builds language selectors based on Prettier's supported languages + plugins
 
-**ModuleResolver** (`src/ModuleResolver.ts`):
+**ModuleResolver** (`src/ModuleResolverNode.ts` for desktop, `src/ModuleResolverWeb.ts` for browser):
 
-- Resolves local/global Prettier installations
-- Falls back to bundled Prettier if none found
-- Caches resolved modules and configurations
-- Handles Workspace Trust restrictions
+- **Desktop (ModuleResolverNode.ts)**: Resolves local/global Prettier installations, falls back to bundled Prettier, caches resolved modules, handles Workspace Trust
+- **Browser (ModuleResolverWeb.ts)**: Uses bundled Prettier standalone with all built-in plugins
 
-**Prettier Instance** (`PrettierInstance.ts`, `PrettierMainThreadInstance.ts`, `PrettierWorkerInstance.ts`):
+**Prettier Instance** (`src/PrettierDynamicInstance.ts`):
 
-- `PrettierInstance` is an interface with two implementations
-- `PrettierMainThreadInstance` loads Prettier directly via `require()`
-- `PrettierWorkerInstance` loads Prettier in a worker thread to avoid blocking
+- Implements the `PrettierInstance` interface (defined in `src/types.ts`)
+- Loads Prettier dynamically using ESM `import()` for lazy loading
 - Works with both Prettier v2 and v3+
 
 ### Bundling
 
 esbuild produces two bundles:
 
 - Node bundle (`dist/extension.js`) for desktop VS Code
-- Web bundle (`dist/web-extension.js`) for vscode.dev/browser
+- Web bundle (`dist/web-extension.cjs`) for vscode.dev/browser
 
-The browser build uses path aliasing to swap `ModuleResolver` → `BrowserModuleResolver`.
+The browser build uses path aliasing to swap `ModuleResolverNode.ts` → `ModuleResolverWeb.ts`.
 
 Build configuration is in `esbuild.mjs`.
 

CONTRIBUTING.md

@@ -90,7 +90,6 @@ Key components:
 
 - `PrettierEditService.ts` - Handles document formatting
 - `ModuleResolver.ts` - Resolves Prettier installations (local, global, or bundled)
-- `PrettierInstance.ts` - Interface for Prettier, with `PrettierMainThreadInstance` and `PrettierWorkerInstance` implementations
 
 ## Submitting Changes