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'
 import process from 'node:process'
 
-import { getPort } from 'get-port-please'
+import { checkPort, getPort } from 'get-port-please'
 import colors from 'picocolors'
 
 import { debug, logger } from '../utils/logger'
@@ -19,6 +19,8 @@ import { startTunnel } from './tunnel'
 
 export interface ListenOptions {
   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 =
   const hostname = options.hostname ?? (options.public ? '' : 'localhost')
 
   const requestedPort = options.port === undefined || options.port === '' ? undefined : Number(options.port)
-  const port = requestedPort === 0
-    ? await getPort({ random: true, host: hostname || undefined })
-    : await getPort({
-        port: requestedPort,
-        alternativePortRange: [3000, 3100],
-        host: hostname || undefined,
-      })
-  if (requestedPort && port !== requestedPort) {
-    logger.warn(`Port ${requestedPort} is in use, using port ${port} instead.`)
-  }
+  const port = await resolvePort(requestedPort, hostname, options.strictPort)
 
   const httpsOptions = options.https === true ? {} : options.https
   const certificate = httpsOptions ? await resolveCertificate(httpsOptions) : false
@@ -228,6 +221,30 @@ export async function listen(handler: RequestListener, options: ListenOptions =
   }
 }
 
+async function resolvePort(requestedPort: number | undefined, hostname: string, strictPort?: boolean): Promise<number> {
+  if (requestedPort === 0) {
+    return getPort({ random: true, host: hostname || undefined })
+  }
+
+  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
+  }
+
+  const port = await getPort({
+    port: requestedPort,
+    alternativePortRange: [3000, 3100],
+    host: hostname || undefined,
+  })
+  if (requestedPort && port !== requestedPort) {
+    logger.warn(`Port ${requestedPort} is in use, using port ${port} instead.`)
+  }
+  return port
+}
+
 function centerBlock(block: string): string {
   const lines = block.split('\n')
   const width = Math.max(...lines.map(line => line.length))

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

@@ -1,11 +1,13 @@
+import type { 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', () => {
+  const listeners: Listener[] = []
+
+  afterEach(async () => {
+    await Promise.all(listeners.splice(0).map(listener => listener.close()))
+  })
+
+  async function start(options: Parameters<typeof listen>[1]) {
+    const listener = await listen((_req, res) => res.end('ok'), { showURL: false, ...options })
+    listeners.push(listener)
+    return listener
+  }
+
+  it('should fall back to another port by default', async () => {
+    const first = await start({ port: 0 })
+    const second = await start({ port: first.address.port })
+
+    expect(second.address.port).not.toBe(first.address.port)
+  })
+
+  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/)
+  })
+
+  it('should use the requested port with `strictPort`', async () => {
+    const { address } = await start({ port: 0 })
+    const port = address.port
+    await Promise.all(listeners.splice(0).map(listener => listener.close()))
+
+    const listener = await start({ port, strictPort: true })
+    expect(listener.address.port).toBe(port)
+  })
+})