refactor: update README and remove redundant standalone server handling in Server class

Author: bjohansebas

examples/api/plugin/README.md

@@ -38,10 +38,9 @@ npx webpack --watch
 
 ## Notes
 
-- Use `webpack --watch`, not `webpack serve`. `webpack serve` creates its own
-  standalone dev server; if you also have a plugin instance in `plugins[]`,
-  the plugin detects the standalone server and stays passive to avoid binding
-  the same port twice.
-- A plain `webpack` build (no watch) will not start the server — the plugin
-  detects build mode and stays passive so the build can finish and the process
-  can exit normally.
+- The plugin works with both `webpack --watch` and `webpack serve`. With
+  `webpack serve`, `webpack-cli` already creates its own standalone dev server
+  for the same compiler, so you would end up with two servers running. If
+  that's intentional (e.g. different ports/hosts), make sure the plugin's
+  `port` does not clash with the one `webpack-cli` resolves from
+  `config.devServer` and CLI args. Otherwise prefer one or the other.

lib/Server.js

@@ -328,20 +328,6 @@ 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]
@@ -3374,36 +3360,8 @@ class Server {
    * @returns {Promise<void>}
    */
   async start() {
-    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);
-      }
-    }
+    await this.setup();
+    await this.listen();
   }
 
   /**
@@ -3520,8 +3478,6 @@ class Server {
    * @returns {Promise<void>}
    */
   async stop() {
-    this.#trackStandalone(false);
-
     if (this.bonjour) {
       await /** @type {Promise<void>} */ (
         new Promise((resolve) => {
@@ -3642,21 +3598,6 @@ class Server {
     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 —
@@ -3669,7 +3610,7 @@ class Server {
      * @returns {Promise<void>} promise
      */
     const ensureSetup = () => {
-      if (isStandaloneRunning() || isBuildMode()) return Promise.resolve();
+      if (isBuildMode()) return Promise.resolve();
       if (!setupPromise) {
         setupPromise = this.setup();
       }
@@ -3681,7 +3622,7 @@ class Server {
      * @returns {Promise<void>} promise
      */
     const onChildDone = async (childCompiler) => {
-      if (listening || isStandaloneRunning() || isBuildMode()) return;
+      if (listening || isBuildMode()) return;
       if (seenFirstDone.has(childCompiler)) return;
       seenFirstDone.add(childCompiler);
       firstDoneCount++;

test/e2e/api-plugin.test.js

@@ -343,31 +343,5 @@ describe("API (plugin)", () => {
         });
       }
     });
-
-    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();
-      }
-    });
   });
 });