refactor: migrate to ES module syntax

.gitignore

@@ -7,6 +7,9 @@ npm-debug.log
 client
 !/examples/client
 !/test/client
+
+examples/**/dist
+
 coverage
 node_modules
 .vscode

babel.config.js

@@ -1,6 +1,4 @@
-"use strict";
-
-module.exports = (api) => {
+export default (api) => {
   api.cache(true);
 
   return {
@@ -24,7 +22,7 @@ module.exports = (api) => {
             "@babel/preset-env",
             {
               targets: {
-                node: "20.9.0",
+                node: "22.15.0",
               },
             },
           ],

bin/webpack-dev-server.js

@@ -2,17 +2,22 @@
 /* Based on webpack/bin/webpack.js */
 /* eslint-disable no-console */
 
-"use strict";
+import cp from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import readLine from "node:readline";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import fs from "graceful-fs";
+
+const require = createRequire(import.meta.url);
 
 /**
  * @param {string} command process to run
  * @param {string[]} args command line arguments
  * @returns {Promise<void>} promise
  */
-const runCommand = (command, args) => {
-  const cp = require("node:child_process");
-
-  return new Promise((resolve, reject) => {
+const runCommand = (command, args) =>
+  new Promise((resolve, reject) => {
     const executedCommand = cp.spawn(command, args, {
       stdio: "inherit",
       shell: true,
@@ -30,7 +35,6 @@ const runCommand = (command, args) => {
       }
     });
   });
-};
 
 /**
  * @param {string} packageName name of the package
@@ -41,63 +45,30 @@ const isInstalled = (packageName) => {
     return true;
   }
 
-  const path = require("node:path");
-  const fs = require("graceful-fs");
-
-  let dir = __dirname;
-
-  do {
-    try {
-      if (
-        fs.statSync(path.join(dir, "node_modules", packageName)).isDirectory()
-      ) {
-        return true;
-      }
-    } catch {
-      // Nothing
-    }
-  } while (dir !== (dir = path.dirname(dir)));
-
-  // https://github.com/nodejs/node/blob/v18.9.1/lib/internal/modules/cjs/loader.js#L1274
-  // @ts-expect-error
-  for (const internalPath of require("node:module").globalPaths) {
-    try {
-      if (fs.statSync(path.join(internalPath, packageName)).isDirectory()) {
-        return true;
-      }
-    } catch {
-      // Nothing
-    }
+  try {
+    require.resolve(packageName);
+    return true;
+  } catch {
+    return false;
   }
-
-  return false;
 };
 
 /**
  * @param {CliOption} cli options
- * @returns {void}
+ * @returns {Promise<void>}
  */
-const runCli = (cli) => {
+const runCli = async (cli) => {
   if (cli.preprocess) {
     cli.preprocess();
   }
 
-  const path = require("node:path");
-
-  const pkgPath = require.resolve(`${cli.package}/package.json`);
+  const pkgUrl = import.meta.resolve(`${cli.package}/package.json`);
+  const pkgPath = fileURLToPath(pkgUrl);
+  const pkg = (await import(pkgUrl, { with: { type: "json" } })).default;
 
-  const pkg = require(pkgPath);
+  const binPath = path.resolve(path.dirname(pkgPath), pkg.bin[cli.binName]);
 
-  if (pkg.type === "module" || /\.mjs/i.test(pkg.bin[cli.binName])) {
-    import(path.resolve(path.dirname(pkgPath), pkg.bin[cli.binName])).catch(
-      (error) => {
-        console.error(error);
-        process.exitCode = 1;
-      },
-    );
-  } else {
-    require(path.resolve(path.dirname(pkgPath), pkg.bin[cli.binName]));
-  }
+  await import(pathToFileURL(binPath).href);
 };
 
 /**
@@ -123,10 +94,6 @@ const cli = {
 };
 
 if (!cli.installed) {
-  const path = require("node:path");
-  const fs = require("graceful-fs");
-  const readLine = require("node:readline");
-
   const notify = `CLI for webpack must be installed.\n  ${cli.name} (${cli.url})\n`;
 
   console.error(notify);
@@ -187,14 +154,17 @@ if (!cli.installed) {
     );
 
     runCommand(packageManager, [...installOptions, cli.package])
-      .then(() => {
-        runCli(cli);
-      })
+      .then(() => runCli(cli))
       .catch((error) => {
         console.error(error);
         process.exitCode = 1;
       });
   });
 } else {
-  runCli(cli);
+  try {
+    await runCli(cli);
+  } catch (error) {
+    console.error(error);
+    process.exitCode = 1;
+  }
 }

client-src/clients/WebSocketClient.js

@@ -1,6 +1,6 @@
 import { log } from "../utils/log.js";
 
-/** @typedef {import("../index").EXPECTED_ANY} EXPECTED_ANY */
+/** @typedef {import("../index.js").EXPECTED_ANY} EXPECTED_ANY */
 
 /**
  * @implements {CommunicationClient}

client-src/globals.d.ts

@@ -20,5 +20,5 @@ declare module "ansi-html-community" {
     function setColors(colors: Record<string, string | string[]>): void;
   }
 
-  export = ansiHtmlCommunity;
+  export default ansiHtmlCommunity;
 }

client-src/index.js

@@ -9,7 +9,7 @@ import socket from "./socket.js";
 import { log, setLogLevel } from "./utils/log.js";
 import sendMessage from "./utils/sendMessage.js";
 
-// eslint-disable-next-line jsdoc/no-restricted-syntax
+// eslint-disable-next-line jsdoc/reject-any-type
 /** @typedef {any} EXPECTED_ANY */
 
 /**

client-src/overlay.js

@@ -3,7 +3,7 @@
 
 import ansiHTML from "ansi-html-community";
 
-/** @typedef {import("./index").EXPECTED_ANY} EXPECTED_ANY */
+/** @typedef {import("./index.js").EXPECTED_ANY} EXPECTED_ANY */
 
 /**
  * @type {(input: string, position: number) => number | undefined}
@@ -79,16 +79,16 @@ function encode(text) {
 
 /**
  * @typedef {object} Context
- * @property {'warning' | 'error'} level level
- * @property {(string  | Message)[]} messages messages
- * @property {'build' | 'runtime'} messageSource message source
+ * @property {"warning" | "error"} level level
+ * @property {(string | Message)[]} messages messages
+ * @property {"build" | "runtime"} messageSource message source
  */
 
 /** @typedef {{ type: string } & Record<string, EXPECTED_ANY>} Event */
 
 /**
  * @typedef {object} Options
- * @property {{ [state: string]: { on: Record<string, { target: string; actions?: Array<string> }> } }} states states
+ * @property {{ [state: string]: { on: Record<string, { target: string, actions?: string[] }> } }} states states
  * @property {Context} context context
  * @property {string} initial initial
  */
@@ -149,9 +149,9 @@ function createMachine({ states, context, initial }, { actions }) {
 
 /**
  * @typedef {object} ShowOverlayData
- * @property {'warning' | 'error'} level level
- * @property {(string  | Message)[]} messages messages
- * @property {'build' | 'runtime'} messageSource message source
+ * @property {"warning" | "error"} level level
+ * @property {(string | Message)[]} messages messages
+ * @property {"build" | "runtime"} messageSource message source
  */
 
 /**
@@ -390,7 +390,7 @@ const colors = {
 
 ansiHTML.setColors(colors);
 
-/** @typedef {Error & { file?: string, moduleName?: string, moduleIdentifier?: string, loc?: string, message?: string; stack?: string | string[] }} Message */
+/** @typedef {Error & { file?: string, moduleName?: string, moduleIdentifier?: string, loc?: string, message?: string, stack?: string | string[] }} Message */
 
 /**
  * @param {string} type type
@@ -450,7 +450,7 @@ const createOverlay = (options) => {
   let containerElement;
   /** @type {HTMLDivElement | null | undefined} */
   let headerElement;
-  /** @type {Array<(element: HTMLDivElement) => void>} */
+  /** @type {((element: HTMLDivElement) => void)[]} */
   let onLoadQueue = [];
   /** @type {Omit<TrustedTypePolicy, "createScript" | "createScriptURL"> | undefined} */
   let overlayTrustedTypesPolicy;
@@ -589,7 +589,7 @@ const createOverlay = (options) => {
    * @param {string} type type
    * @param {(string | Message)[]} messages messages
    * @param {undefined | false | string} trustedTypesPolicyName trusted types policy name
-   * @param {'build' | 'runtime'} messageSource message source
+   * @param {"build" | "runtime"} messageSource message source
    */
   function show(type, messages, trustedTypesPolicyName, messageSource) {
     ensureOverlayExists(() => {

client-src/utils/sendMessage.js

@@ -1,6 +1,6 @@
 /* global WorkerGlobalScope */
 
-/** @typedef {import("../index").EXPECTED_ANY} EXPECTED_ANY */
+/** @typedef {import("../index.js").EXPECTED_ANY} EXPECTED_ANY */
 
 // Send messages to the outside, so plugins can consume it.
 /**

client-src/webpack.config.js

@@ -1,23 +1,22 @@
-"use strict";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import webpack from "webpack";
+import { merge } from "webpack-merge";
 
-const path = require("node:path");
-const webpack = require("webpack");
-const { merge } = require("webpack-merge");
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 const library = {
   library: {
-    // type: "module",
-    type: "commonjs",
+    type: "module",
   },
 };
 
 const baseForModules = {
   devtool: false,
   mode: "development",
-  // TODO enable this in future after fix bug with `eval` in webpack
-  // experiments: {
-  //   outputModule: true,
-  // },
+  experiments: {
+    outputModule: true,
+  },
   output: {
     path: path.resolve(__dirname, "../client/modules"),
     ...library,
@@ -37,7 +36,7 @@ const baseForModules = {
   },
 };
 
-module.exports = [
+export default [
   merge(baseForModules, {
     entry: path.join(__dirname, "modules/logger/index.js"),
     output: {

commitlint.config.js

@@ -1,6 +1,4 @@
-"use strict";
-
-module.exports = {
+export default {
   extends: ["@commitlint/config-conventional"],
   rules: {
     "header-max-length": [0],

eslint.config.mjs

@@ -22,10 +22,6 @@ export default defineConfig([
     files: ["test/**/*"],
     extends: [configs["universal-recommended"]],
     rules: {
-      // Tests use experimental node:test APIs intentionally
-      // (mock.module, mock.timers, snapshot.*). The package's engines field
-      // is wider than where these are stable, so silence the linter here.
-      "n/no-unsupported-features/node-builtins": "off",
       // Test callbacks (it/test/subtest arrow functions) don't need JSDoc.
       "jsdoc/require-jsdoc": "off",
       // Tests legitimately log diagnostics (retry attempts, etc.).

examples/README.md

@@ -16,6 +16,27 @@ An example should be as minimal as possible and consists of at least:
 API examples can be found in the `api` directory. These examples demonstrate how
 to access and run `webpack-dev-server` directly in your application / script.
 
+## Module format
+
+Examples are written as ES modules (`import` / `export`) because the project's
+`package.json` sets `"type": "module"`. The shared helper `util.js` exports a
+`setup` function that each `webpack.config.js` calls like this:
+
+```js
+import { setup } from "../util.js";
+
+export default setup(
+  {
+    context: import.meta.dirname,
+    entry: "./app.js",
+  },
+  import.meta.url,
+);
+```
+
+If you still need a CommonJS configuration, see [`default-cjs/`](./default-cjs)
+for a minimal CJS example using a `.cjs` extension.
+
 ## Notes
 
 - Each example's `webpack` config is wrapped with `util.setup`; a helper function

examples/api/find-ip/app.js

@@ -1,6 +1,4 @@
-"use strict";
-
-const WebpackDevServer = require("../../../lib/Server");
+import WebpackDevServer from "../../../lib/Server.js";
 
 const logInternalIPs = async () => {
   const localIPv4 = WebpackDevServer.findIp("v4", false);

examples/api/middleware/app.js

@@ -1,5 +1,3 @@
-"use strict";
-
 const target = document.querySelector("#target");
 
 target.classList.add("pass");

examples/api/middleware/server.js

@@ -1,8 +1,6 @@
-"use strict";
-
-const Webpack = require("webpack");
-const WebpackDevServer = require("../../../lib/Server");
-const webpackConfig = require("./webpack.config");
+import Webpack from "webpack";
+import WebpackDevServer from "../../../lib/Server.js";
+import webpackConfig from "./webpack.config.js";
 
 const compiler = Webpack(webpackConfig);
 const devServerOptions = webpackConfig.devServer;