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'
 importprocessfrom'node:process'
 
-import{checkPort,getPort}from'get-port-please'
+import{getPort}from'get-port-please'
 importcolorsfrom'picocolors'
 
 import{debug,logger}from'../utils/logger'
@@ -117,9 +117,10 @@ export async function listen(handler: RequestListener, options: ListenOptions =
  : createHttpServer(handler)
 
 awaitnewPromise<void>((resolve,reject)=>{
-server.once('error',reject)
+constonError=(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){
-constdesiredPort=requestedPort??3000
-if(awaitcheckPort(desiredPort,hostname||undefined)===false){
-thrownewError(`Port ${desiredPort} is already in use (\`--strictPort\` is enabled).`)
-}
-returndesiredPort
+returnrequestedPort??3000
 }
 
 constport=awaitgetPort({
@@ -250,6 +247,27 @@ async function resolvePort(requestedPort: number | undefined, hostname: string,
 returnport
 }
 
+/**
+ * Turn a `listen()` failure into actionable advice, leaving anything we have
+ * nothing better to say about untouched.
+ */
+functiondescribeBindError(error: NodeJS.ErrnoException,port: number,hostname: string,strictPort?: boolean): Error{
+switch(error.code){
+case'EADDRINUSE':
+returnnewError(
+strictPort
+ ? `Port ${port} is already in use (\`--strictPort\` is enabled).`
+ : `Port ${port} is already in use.`,
+{cause: error},
+)
+case'EACCES':
+returnnewError(`Port ${port} requires elevated privileges. Pass \`--port\` with a port above 1023.`,{cause: error})
+case'EADDRNOTAVAIL':
+returnnewError(`\`${hostname}\` is not an address of this machine. Pass \`--host\` with a local address, or omit it to listen on localhost.`,{cause: error})
+}
+returnerror
+}
+
 exportasyncfunctionprintQRCode(url: string,{ showURL =false}: {showURL?: boolean}={}): Promise<void>{
 const{ renderUnicodeCompact }=awaitimport('uqr')
 constcaption=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()=>{
 constfirst=awaitstart({port: 0})
 
-awaitexpect(start({port: first.address.port,strictPort: true})).rejects.toThrow(/alreadyinuse/)
+awaitexpect(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()=>{
+awaitexpect(start({port: 34567,hostname: '203.0.113.1',strictPort: true})).rejects.toThrow(/isnotanaddressofthismachine/)
 })
 
 it('should open the dev server URL',async()=>{