feat(dev): add --strictPort flag

Author: danielroe

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

@@ -49,6 +49,11 @@ const command = defineCommand({
 description: 'Port to listen on (default: `NUXT_PORT || NITRO_PORT || PORT || nuxtOptions.devServer.port`)',
 alias: ['p'],
 },
+'strictPort': {
+type: 'boolean',
+description: 'Exit if the requested port is unavailable instead of using another one',
+default: false,
+},
 'host': {
 type: 'string',
 description: 'Host to listen on (default: `NUXT_HOST || NITRO_HOST || HOST || nuxtOptions.devServer?.host`)',
@@ -291,6 +296,7 @@ function resolveListenOverrides(args: ParsedArgs<ArgsT>): DevListenOverrides {
 ||process.env.NITRO_PORT
 ||process.env.PORT
 ||undefined,
+strictPort: args.strictPort,
 hostname: host===true||host==='' ? '' : host||undefined,
 open: args.open,
 clipboard: args.clipboard,

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{getPort}from'get-port-please'
+import{checkPort,getPort}from'get-port-please'
 importcolorsfrom'picocolors'
 
 import{debug,logger}from'../utils/logger'
@@ -19,6 +19,8 @@ import { startTunnel } from './tunnel'
 
 exportinterfaceListenOptions{
 port?: string|number
+/** Fail instead of falling back to another port when `port` is unavailable. */
+strictPort?: boolean
 hostname?: string
 baseURL?: string
 showURL?: boolean
@@ -98,16 +100,7 @@ export async function listen(handler: RequestListener, options: ListenOptions =
 consthostname=options.hostname??(options.public ? '' : 'localhost')
 
 constrequestedPort=options.port===undefined||options.port==='' ? undefined : Number(options.port)
-constport=requestedPort===0
- ? awaitgetPort({random: true,host: hostname||undefined})
- : awaitgetPort({
-port: requestedPort,
-alternativePortRange: [3000,3100],
-host: hostname||undefined,
-})
-if(requestedPort&&port!==requestedPort){
-logger.warn(`Port ${requestedPort} is in use, using port ${port} instead.`)
-}
+constport=awaitresolvePort(requestedPort,hostname,options.strictPort)
 
 consthttpsOptions=options.https===true ? {} : options.https
 constcertificate=httpsOptions ? awaitresolveCertificate(httpsOptions) : false
@@ -228,6 +221,30 @@ export async function listen(handler: RequestListener, options: ListenOptions =
 }
 }
 
+asyncfunctionresolvePort(requestedPort: number|undefined,hostname: string,strictPort?: boolean): Promise<number>{
+if(requestedPort===0){
+returngetPort({random: true,host: hostname||undefined})
+}
+
+if(strictPort){
+constdesiredPort=requestedPort??3000
+if(awaitcheckPort(desiredPort,hostname||undefined)===false){
+thrownewError(`Port ${desiredPort} is already in use (\`--strictPort\` is enabled).`)
+}
+returndesiredPort
+}
+
+constport=awaitgetPort({
+port: requestedPort,
+alternativePortRange: [3000,3100],
+host: hostname||undefined,
+})
+if(requestedPort&&port!==requestedPort){
+logger.warn(`Port ${requestedPort} is in use, using port ${port} instead.`)
+}
+returnport
+}
+
 functioncenterBlock(block: string): string{
 constlines=block.split('\n')
 constwidth=Math.max(...lines.map(line=>line.length))

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

@@ -1,11 +1,13 @@
+importtype{Listener}from'../../src/dev/listen'
+
 import{networkInterfaces}from'node:os'
 
-import{describe,expect,it,vi}from'vitest'
+import{afterEach,describe,expect,it,vi}from'vitest'
 
-import{getNetworkAddresses,resolveOpenCommand}from'../../src/dev/listen'
+import{getNetworkAddresses,listen,resolveOpenCommand}from'../../src/dev/listen'
 
 vi.mock('node:os',()=>({
-networkInterfaces: vi.fn(),
+networkInterfaces: vi.fn(()=>({})),
 release: ()=>'test',
 }))
 
@@ -62,3 +64,39 @@ describe('resolveOpenCommand', () => {
 expect(resolveOpenCommand(url,'darwin',{BROWSER: '/usr/local/bin/firefox'})).toEqual(['/usr/local/bin/firefox',[url]])
 })
 })
+
+describe('listen',()=>{
+constlisteners: Listener[]=[]
+
+afterEach(async()=>{
+awaitPromise.all(listeners.splice(0).map(listener=>listener.close()))
+})
+
+asyncfunctionstart(options: Parameters<typeoflisten>[1]){
+constlistener=awaitlisten((_req,res)=>res.end('ok'),{showURL: false, ...options})
+listeners.push(listener)
+returnlistener
+}
+
+it('should fall back to another port by default',async()=>{
+constfirst=awaitstart({port: 0})
+constsecond=awaitstart({port: first.address.port})
+
+expect(second.address.port).not.toBe(first.address.port)
+})
+
+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/)
+})
+
+it('should use the requested port with `strictPort`',async()=>{
+const{ address }=awaitstart({port: 0})
+constport=address.port
+awaitPromise.all(listeners.splice(0).map(listener=>listener.close()))
+
+constlistener=awaitstart({ port,strictPort: true})
+expect(listener.address.port).toBe(port)
+})
+})