feat: add support for multiple independent plugin servers and enhance port mapping

Author: bjohansebas

lib/Server.js

@@ -328,6 +328,20 @@ const DEFAULT_ALLOWED_PROTOCOLS = /^(file|.+-extension):/i;
 
 const pluginName = "webpack-dev-server";
 
+/**
+ * Tracks compilers that have an active standalone `Server` attached
+ * (`new Server(options, compiler).start()`). When a compiler is in this set,
+ * any `Server` plugin attached to it (or to a `MultiCompiler` that contains
+ * it) stays passive — otherwise we'd try to bind the same port twice.
+ * Particularly relevant for `webpack serve`, which creates its own standalone
+ * server even when the user already added a `Server` instance to `plugins[]`.
+ *
+ * Uses a `WeakSet` so a compiler that is no longer referenced anywhere can be
+ * garbage collected normally, without this module holding it alive.
+ * @type {WeakSet<Compiler | MultiCompiler>}
+ */
+const activeStandaloneCompilers = new WeakSet();
+
 /**
  * @template {BasicApplication} [A=ExpressApplication]
  * @template {BasicServer} [S=HTTPServer]
@@ -1359,7 +1373,12 @@ class Server {
     }
 
     if (typeof options.setupExitSignals === "undefined") {
-      options.setupExitSignals = true;
+      // In plugin mode, the host (e.g. `webpack-cli`) usually owns process
+      // signal handling and calls `compiler.close()` on shutdown, which fires
+      // our `shutdown` hook. Adding our own SIGINT/SIGTERM listeners on top of
+      // that would race with the host's handler and call `compiler.close()`
+      // twice.
+      options.setupExitSignals = !this.isPlugin;
     }
 
     if (typeof options.static === "undefined") {
@@ -3355,8 +3374,36 @@ class Server {
    * @returns {Promise<void>}
    */
   async start() {
-    await this.setup();
-    await this.listen();
+    this.#trackStandalone(true);
+    try {
+      await this.setup();
+      await this.listen();
+    } catch (error) {
+      this.#trackStandalone(false);
+      throw error;
+    }
+  }
+
+  /**
+   * @param {boolean} active whether to mark or unmark the compiler(s) as
+   * having an active standalone server
+   * @returns {void}
+   */
+  #trackStandalone(active) {
+    if (!this.compiler) return;
+    const compilers = /** @type {MultiCompiler} */ (this.compiler)
+      .compilers || [this.compiler];
+    if (active) {
+      activeStandaloneCompilers.add(this.compiler);
+      for (const child of compilers) {
+        activeStandaloneCompilers.add(child);
+      }
+    } else {
+      activeStandaloneCompilers.delete(this.compiler);
+      for (const child of compilers) {
+        activeStandaloneCompilers.delete(child);
+      }
+    }
   }
 
   /**
@@ -3473,6 +3520,8 @@ class Server {
    * @returns {Promise<void>}
    */
   async stop() {
+    this.#trackStandalone(false);
+
     if (this.bonjour) {
       await /** @type {Promise<void>} */ (
         new Promise((resolve) => {
@@ -3588,27 +3637,51 @@ class Server {
     let listening = false;
     let stopped = false;
 
+    const childCompilers = /** @type {MultiCompiler} */ (compiler)
+      .compilers || [compiler];
+    const seenFirstDone = new WeakSet();
+    let firstDoneCount = 0;
+
+    // Returns true when a standalone `Server` is already attached to our
+    // compiler (or any of its children). This matters for `webpack serve`:
+    // it creates its own standalone server even if the user added a `Server`
+    // instance to `plugins[]`. In that case the plugin must stay passive —
+    // otherwise we'd try to bind the same port twice. Independent
+    // server/compiler pairs in the same process are unaffected because they
+    // don't share any compiler instance.
+    const isStandaloneRunning = () => {
+      if (activeStandaloneCompilers.has(compiler)) return true;
+      for (const child of childCompilers) {
+        if (activeStandaloneCompilers.has(child)) return true;
+      }
+      return false;
+    };
+
+    // A one-shot `compiler.run()` (plain `webpack` build) is detected when no
+    // child compiler is in watch mode. In that case we skip both `setup()` and
+    // `listen()` so the build can finish and the process can exit normally —
+    // the user is not in control of the plugin lifecycle here, so we stay
+    // silent rather than logging a warning.
+    const isBuildMode = () =>
+      childCompilers.every((child) => !child.watching && !child.options.watch);
+
     /**
      * @returns {Promise<void>} promise
      */
     const ensureSetup = () => {
+      if (isStandaloneRunning() || isBuildMode()) return Promise.resolve();
       if (!setupPromise) {
         setupPromise = this.setup();
       }
       return setupPromise;
     };
 
-    const childCompilers = /** @type {MultiCompiler} */ (compiler)
-      .compilers || [compiler];
-    const seenFirstDone = new WeakSet();
-    let firstDoneCount = 0;
-
     /**
      * @param {Compiler} childCompiler child compiler
      * @returns {Promise<void>} promise
      */
     const onChildDone = async (childCompiler) => {
-      if (listening) return;
+      if (listening || isStandaloneRunning() || isBuildMode()) return;
       if (seenFirstDone.has(childCompiler)) return;
       seenFirstDone.add(childCompiler);
       firstDoneCount++;

test/e2e/api-plugin.test.js

@@ -7,6 +7,7 @@ const multiCompilerConfig = require("../fixtures/multi-compiler-two-configuratio
 const compile = require("../helpers/compile");
 const runBrowser = require("../helpers/run-browser");
 const port = require("../ports-map")["api-plugin"];
+const [portA, portB] = require("../ports-map")["api-plugin-multi"];
 
 describe("API (plugin)", () => {
   it("should work with plugin API", async () => {
@@ -258,5 +259,77 @@ describe("API (plugin)", () => {
       expect(stopSpy).toHaveBeenCalledTimes(1);
       stopSpy.mockRestore();
     });
+
+    it("should run two independent plugin servers on different child compilers", async () => {
+      const serverA = new Server({ port: portA });
+      const serverB = new Server({ port: portB });
+      const [configA, configB] = multiCompilerConfig;
+      const compiler = webpack([
+        { ...configA, plugins: [...configA.plugins, serverA] },
+        { ...configB, plugins: [...configB.plugins, serverB] },
+      ]);
+
+      await compile(compiler, portA);
+      // The second server is independent, but `compile()` only awaits one
+      // port, so poll the second one until it answers.
+      await new Promise((resolve) => {
+        const interval = setInterval(async () => {
+          try {
+            await fetch(`http://127.0.0.1:${portB}/`);
+            clearInterval(interval);
+            resolve();
+          } catch {
+            // Server not ready yet; keep polling.
+          }
+        }, 100);
+      });
+
+      const { page, browser } = await runBrowser();
+
+      try {
+        const responseA = await page.goto(
+          `http://127.0.0.1:${portA}/one-main.html`,
+          { waitUntil: "networkidle0" },
+        );
+        expect(responseA.status()).toBe(200);
+
+        const responseB = await page.goto(
+          `http://127.0.0.1:${portB}/two-main.html`,
+          { waitUntil: "networkidle0" },
+        );
+        expect(responseB.status()).toBe(200);
+      } finally {
+        await browser.close();
+        await new Promise((resolve) => {
+          compiler.close(resolve);
+        });
+      }
+    });
+
+    it("should stay passive when a standalone server runs on the same compiler", async () => {
+      const compiler = webpack(config);
+      const pluginServer = new Server({ port });
+      const standaloneServer = new Server({ port }, compiler);
+
+      const pluginSetupSpy = jest.spyOn(pluginServer, "setup");
+      const pluginListenSpy = jest.spyOn(pluginServer, "listen");
+
+      pluginServer.apply(compiler);
+      await standaloneServer.start();
+
+      try {
+        // The standalone server drives compilation through its own
+        // webpack-dev-middleware. The plugin's hooks fire during that
+        // compilation but must stay passive — so the plugin's own setup() and
+        // listen() are never called.
+        expect(pluginSetupSpy).not.toHaveBeenCalled();
+        expect(pluginListenSpy).not.toHaveBeenCalled();
+      } finally {
+        pluginSetupSpy.mockRestore();
+        pluginListenSpy.mockRestore();
+        await standaloneServer.stop();
+        await pluginServer.stop();
+      }
+    });
   });
 });

test/ports-map.js

@@ -79,6 +79,7 @@ const listOfTests = {
   app: 1,
   "cross-origin-request": 2,
   "api-plugin": 1,
+  "api-plugin-multi": 2,
 };
 
 let startPort = 8089;