From 40e9db50aa09cf543d77eb39e5aa3d5a23ce3a55 Mon Sep 17 00:00:00 2001
From: Dustin Popp <dustinpopp@ibm.com>
Date: Tue, 3 Dec 2024 11:15:49 -0600
Subject: [PATCH] docs: add v5 migration note for app.listen

Adds a note to the `migrating-5` guide alerting users that error events
received by a server will now cause the callback argument in `app.listen` to
be invoked. In Express 4, this was not the case and errors would be thrown.

Resolves https://github.com/expressjs/express/issues/6191

Signed-off-by: Dustin Popp <dustinpopp@ibm.com>
Co-authored-by: M. Heide <66078329+heidemn-faro@users.noreply.github.com>
---
 en/guide/migrating-5.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/en/guide/migrating-5.md b/en/guide/migrating-5.md
index a99f1b2185..d338d5ab80 100755
--- a/en/guide/migrating-5.md
+++ b/en/guide/migrating-5.md
@@ -45,6 +45,7 @@ You can then run your automated tests to see what fails, and fix problems accord
   <li><a href="#path-syntax">Path route matching syntax</a></li>
   <li><a href="#rejected-promises">Rejected promises handled from middleware and handlers</a></li>
   <li><a href="#express.urlencoded">express.urlencoded</a></li>
+  <li><a href="#app.listen">app.listen</a></li>
   <li><a href="#app.router">app.router</a></li>
   <li><a href="#req.body">req.body</a></li>
   <li><a href="#req.host">req.host</a></li>
@@ -159,6 +160,20 @@ Details of how Express handles errors is covered in the [error handling document
 
 The `express.urlencoded` method makes the `extended` option `false` by default.
 
+<h4 id="app.listen">app.listen</h4>
+
+In Express 5, the `app.listen` method will invoke the user-provided callback function (if provided) when the server receives an error event. In Express 4, such errors would be thrown. This change shifts error-handling responsibility to the callback function in Express 5. If there is an error, it will be passed to the callback as an argument.
+For example:
+
+```js
+const server = app.listen(8080, '0.0.0.0', (error) => {
+  if (error) {
+    throw error; // e.g. EADDRINUSE
+  }
+  console.log('Listening on ' + JSON.stringify(server.address()));
+});
+```
+
 <h4 id="app.router">app.router</h4>
 
 The `app.router` object, which was removed in Express 4, has made a comeback in Express 5. In the new version, this object is a just a reference to the base Express router, unlike in Express 3, where an app had to explicitly load it.