fix(dev): bind directly with --strictPort and translate bind errors

Author: danielroe

packages/nuxt-cli/src/dev/listen.ts

@@ -9,7 +9,7 @@ import { createServer as createHttpsServer } from 'node:https'
 import { networkInterfaces, release } from 'node:os'
 import process from 'node:process'
 
-import { checkPort, getPort } from 'get-port-please'
+import { getPort } from 'get-port-please'
 import colors from 'picocolors'
 
 import { debug, logger } from '../utils/logger'
@@ -117,9 +117,10 @@ export async function listen(handler: RequestListener, options: ListenOptions =
     : createHttpServer(handler)
 
   await new Promise<void>((resolve, reject) => {
-    server.once('error', reject)
+    const onError = (error: NodeJS.ErrnoException) => reject(describeBindError(error, port, hostname, options.strictPort))
+    server.once('error', onError)
     server.listen(port, hostname || undefined, () => {
-      server.removeListener('error', reject)
+      server.removeListener('error', onError)
       // Without a persistent handler, any later `error` event is unhandled and
       // takes the whole dev process down.
       server.on('error', error => logger.error(`Dev server error: ${error.message}`))
@@ -232,11 +233,7 @@ async function resolvePort(requestedPort: number | undefined, hostname: string,
   }
 
   if (strictPort) {
-    const desiredPort = requestedPort ?? 3000
-    if (await checkPort(desiredPort, hostname || undefined) === false) {
-      throw new Error(`Port ${desiredPort} is already in use (\`--strictPort\` is enabled).`)
-    }
-    return desiredPort
+    return requestedPort ?? 3000
   }
 
   const port = await getPort({
@@ -250,6 +247,27 @@ async function resolvePort(requestedPort: number | undefined, hostname: string,
   return port
 }
 
+/**
+ * Turn a `listen()` failure into actionable advice, leaving anything we have
+ * nothing better to say about untouched.
+ */
+function describeBindError(error: NodeJS.ErrnoException, port: number, hostname: string, strictPort?: boolean): Error {
+  switch (error.code) {
+    case 'EADDRINUSE':
+      return new Error(
+        strictPort
+          ? `Port ${port} is already in use (\`--strictPort\` is enabled).`
+          : `Port ${port} is already in use.`,
+        { cause: error },
+      )
+    case 'EACCES':
+      return new Error(`Port ${port} requires elevated privileges. Pass \`--port\` with a port above 1023.`, { cause: error })
+    case 'EADDRNOTAVAIL':
+      return new Error(`\`${hostname}\` is not an address of this machine. Pass \`--host\` with a local address, or omit it to listen on localhost.`, { cause: error })
+  }
+  return error
+}
+
 export async function printQRCode(url: string, { showURL = false }: { showURL?: boolean } = {}): Promise<void> {
   const { renderUnicodeCompact } = await import('uqr')
   const caption = showURL ? `\n${centerBlock(colors.cyan(url), url.length)}` : ''

packages/nuxt-cli/test/unit/listen.spec.ts

@@ -118,7 +118,11 @@ describe('listen', () => {
   it('should throw for a busy port with `strictPort`', async () => {
     const first = await start({ port: 0 })
 
-    await expect(start({ port: first.address.port, strictPort: true })).rejects.toThrow(/already in use/)
+    await expect(start({ port: first.address.port, strictPort: true })).rejects.toThrow(`Port ${first.address.port} is already in use (\`--strictPort\` is enabled).`)
+  })
+
+  it('should explain an unavailable host', async () => {
+    await expect(start({ port: 34567, hostname: '203.0.113.1', strictPort: true })).rejects.toThrow(/is not an address of this machine/)
   })
 
   it('should open the dev server URL', async () => {