perf(dev): bind the dev server port before the config is loaded

Author: danielroe

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

@@ -101,18 +101,43 @@ const HOSTNAME_RE = /^(?!-)[\d.:a-z-]{1,253}(?<!-)$/i
  * Check `hostname` is a plausible host or IP address, falling back to a
  * bindable default (with a warning) when it is not.
  */
-exportfunctionvalidateHostname(hostname: string|undefined,isPublic?: boolean): string|undefined{
+exportfunctionvalidateHostname(hostname: string|undefined,isPublic?: boolean,options: {silent?: boolean}={}): string|undefined{
 constisValid=!!hostname
 &&HOSTNAME_RE.test(hostname)
 &&hostname.split('.').every(label=>label.length<=63)
 if(!hostname||isValid){
 returnhostname
 }
 constfallback=isPublic ? '' : 'localhost'
-logger.warn(`Invalid host \`${hostname}\`, using \`${fallback||'0.0.0.0'}\` instead.`)
+if(!options.silent){
+logger.warn(`Invalid host \`${hostname}\`, using \`${fallback||'0.0.0.0'}\` instead.`)
+}
 returnfallback
 }
 
+/** Hostname `bindListener` will bind for `options`. */
+functionresolveBindHostname(options: ListenOptions,silent=false): string{
+constisolated=options.hostname===undefined&&!options.public&&detectIsolatedEnvironment()
+returnvalidateHostname(options.hostname,options.public,{ silent })??(options.public||isolated ? '' : 'localhost')
+}
+
+/**
+ * Whether an already bound server can serve `options`, so a listener bound
+ * before the Nuxt config was known can be kept rather than rebound.
+ */
+exportfunctionmatchesBoundTarget(bound: BoundServer,options: ListenOptions): boolean{
+if(resolveBindHostname(options,true)!==bound.hostname){
+returnfalse
+}
+if(!!options.https!==!!bound.https){
+returnfalse
+}
+// Parsed leniently: an unusable port cannot match, and reporting that is
+// `bindListener`'s job rather than this comparison's.
+constport=options.port===undefined||options.port==='' ? undefined : Number(options.port)
+returnport===undefined||port===bound.address.port||port===bound.requestedPort
+}
+
 /**
  * External IPv4 addresses other devices can reach. IPv4 link-local addresses
  * (169.254.0.0/16, from a macOS Thunderbolt Bridge or an unconfigured adapter)
@@ -152,9 +177,22 @@ function createSecureServer(certificate: ResolvedCertificate, handler: RequestLi
 }
 }
 
-exportasyncfunctionlisten(handler: RequestListener,options: ListenOptions={}): Promise<Listener>{
-constisolatedEnvironment=options.hostname===undefined&&!options.public&&detectIsolatedEnvironment()
-consthostname=validateHostname(options.hostname,options.public)??(options.public||isolatedEnvironment ? '' : 'localhost')
+/** A bound socket, before any URL resolution, tunnel or console output. */
+exportinterfaceBoundServer{
+server: HttpServer
+address: AddressInfo
+https: false|ResolvedCertificate
+hostname: string
+/** Port that was asked for, before any in-use fallback. */
+requestedPort?: number
+}
+
+/**
+ * Bind a socket and nothing else, so the port can be taken before the Nuxt
+ * config is known and requests can be answered while it loads.
+ */
+exportasyncfunctionbindListener(handler: RequestListener,options: ListenOptions={}): Promise<BoundServer>{
+consthostname=resolveBindHostname(options)
 
 constrequestedPort=parsePort(options.port)
 constport=options.handover&&requestedPort
@@ -178,31 +216,37 @@ export async function listen(handler: RequestListener, options: ListenOptions =
 // takes the whole dev process down.
 server.on('error',error=>logger.error(`Dev server error: ${error.message}`))
 
-// Set inside `createListener`, so a failure after the tunnel is up can still
-// tear down the cloudflared process rather than leaking it until exit.
+return{ server,address: server.address()asAddressInfo,https: certificate, hostname, requestedPort }
+}
+
+/**
+ * Resolve the URLs of an already bound server and, unless `announce` is false,
+ * start any tunnel and print, copy and open the URLs.
+ */
+exportasyncfunctioncreateListener(bound: BoundServer,options: ListenOptions={},{ announce =true}: {announce?: boolean}={}): Promise<Listener>{
+const{ server, address, hostname,https: certificate}=bound
+
+// Set before anything that can throw, so a failure after the tunnel is up can
+// still tear down the cloudflared process rather than leaking it until exit.
 lettunnel: Tunnel|undefined
 
 try{
-returnawaitcreateListener()
+returnawaitresolveListener()
 }
 catch(error){
-awaitPromise.all([
-tunnel?.close().catch(()=>{}),
-closeServer(server).catch(()=>{}),
-])
+awaittunnel?.close().catch(()=>{})
 throwerror
 }
 
-asyncfunctioncreateListener(): Promise<Listener>{
-constaddress=server.address()asAddressInfo
+asyncfunctionresolveListener(): Promise<Listener>{
 constprotocol=certificate ? 'https' : 'http'
 constbaseURL=options.baseURL||'/'
 constformatURL=(host: string)=>formatDisplayURL(protocol,host,address.port,baseURL)
 
 constanyHost=ANY_HOSTS.has(hostname)
 consturl=formatURL(anyHost ? 'localhost' : hostname)
 
-if(options.tunnel){
+if(announce&&options.tunnel){
 const{ startTunnel }=awaitimport('./tunnel')
 tunnel=awaitstartTunnel(`${protocol}://localhost:${address.port}`,!!certificate)
 }
@@ -271,19 +315,21 @@ export async function listen(handler: RequestListener, options: ListenOptions =
 console.log(`${qr ? '' : '\n'}${lines.join('\n')}\n`)
 }
 
-if(options.showURL!==false){
-if(qrURL){
-awaitprintQRCode(qrURL)
+if(announce){
+if(options.showURL!==false){
+if(qrURL){
+awaitprintQRCode(qrURL)
+}
+showURLs({qr: !!qrURL})
 }
-showURLs({qr: !!qrURL})
-}
 
-if(options.clipboard){
-awaitcopyURL(publicURL||url)
-}
+if(options.clipboard){
+awaitcopyURL(publicURL||url)
+}
 
-if(options.open){
-openBrowser(options.openURL ? resolveOpenURL(options.openURL,url) : url)
+if(options.open){
+openBrowser(options.openURL ? resolveOpenURL(options.openURL,url) : url)
+}
 }
 
 return{
@@ -303,6 +349,18 @@ export async function listen(handler: RequestListener, options: ListenOptions =
 }
 }
 
+/** Bind and announce in one step, for callers that already know their config. */
+exportasyncfunctionlisten(handler: RequestListener,options: ListenOptions={}): Promise<Listener>{
+constbound=awaitbindListener(handler,options)
+try{
+returnawaitcreateListener(bound,options)
+}
+catch(error){
+awaitcloseServer(bound.server).catch(()=>{})
+throwerror
+}
+}
+
 functioncloseServer(server: HttpServer): Promise<void>{
 returnnewPromise<void>((resolve,reject)=>{
 letforceClose: NodeJS.Timeout|undefined
@@ -494,7 +552,7 @@ function centerBlock(block: string, blockWidth?: number): string {
 returnlines.map(line=>indent+line).join('\n')
 }
 
-functionresolveOpenURL(target: string,baseURL: string): string{
+exportfunctionresolveOpenURL(target: string,baseURL: string): string{
 try{
 returnnewURL(target,baseURL).href
 }

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

@@ -6,7 +6,7 @@ import type { Server as HttpServer, IncomingMessage, RequestListener, ServerResp
 
 importtype{ResolvedCertificate}from'./cert'
 importtype{InspectOptions}from'./inspect'
-importtype{DevListenOverrides,Listener,ListenOptions}from'./listen'
+importtype{BoundServer,DevListenOverrides,Listener,ListenOptions}from'./listen'
 importtype{DevRestartReason}from'./reason'
 import{Buffer}from'node:buffer'
 import{hash}from'node:crypto'
@@ -24,14 +24,15 @@ import { toNodeHandler } from 'srvx/node'
 import{provider}from'std-env'
 
 import{showBanner}from'../utils/banner'
+import{loadDevServerHint,saveDevServerHint}from'../utils/dev-hint'
 import{ActionableError}from'../utils/errors'
 import{clearBuildDir}from'../utils/fs'
 import{loadKit}from'../utils/kit'
 import{acquireLock,formatLockError,getTakeoverPid,updateLock}from'../utils/lockfile'
 import{debug,logger,writeNotice}from'../utils/logger'
 import{loadNuxtManifest,resolveNuxtManifest,writeNuxtManifest}from'../utils/nuxt'
 import{renderError,renderErrorAnsi}from'./error-lazy'
-import{listen}from'./listen'
+import{bindListener,createListener,matchesBoundTarget,openBrowser,resolveOpenURL}from'./listen'
 import{resolveDefaultLoadingTemplate}from'./loading-template'
 import{resolvePortlessURLs}from'./portless'
 import{formatChangedKeys,formatRestartReason,formatSkippedReload,mergeRestartReasons,withConfigKeys}from'./reason'
@@ -279,6 +280,8 @@ export class NuxtDevServer extends EventEmitter<DevServerEventMap> {
  #pendingReason?: DevRestartReason
  #rawConfig?: Record<string,unknown>
  #changedConfigKeys?: string[]
+ #bound?: BoundServer
+ #openedEagerly =false
 
 loadDebounced: ()=>void
 handler: RequestListener
@@ -374,9 +377,11 @@ export class NuxtDevServer extends EventEmitter<DevServerEventMap> {
 this.#handler =undefined
 this.emit('loading',this.#loadingMessage)
 
-awaitthis.#loadNuxtInstance()
+awaitthis.#bindEagerListener()
 
-// Acquire lock before binding a listener so parallel agent invocations
+awaitthis.#loadNuxtInstance(this.#bound &&this.listener.getURLs().map(({ url })=>url))
+
+// Acquire lock before serving so parallel agent invocations
 // fail fast without starting a second server (agent-only).
 this.#acquireDevLock(this.#currentNuxt!.options.buildDir)
 
@@ -540,13 +545,85 @@ export class NuxtDevServer extends EventEmitter<DevServerEventMap> {
 this.#currentNuxt =awaitkit.loadNuxt(loadOptions)
 }
 
+/**
+ * Bind a socket before the Nuxt config is known, so the port answers within
+ * milliseconds of spawn and pre-ready requests get the loading screen instead
+ * of hanging. The address is taken from the CLI/env, else from the address the
+ * previous run resolved, else from the schema default.
+ *
+ * A guessed address is only a guess: `#createListener` rebinds if the resolved
+ * config disagrees. Set `NUXT_DEV_EAGER_LISTEN=0` to bind after the config instead.
+ */
+async #bindEagerListener(): Promise<void>{
+if(process.env.NUXT_DEV_EAGER_LISTEN==='0'||process.env.NUXT_DEV_EAGER_LISTEN==='false'){
+return
+}
+
+constoverrides=this.options.listenOverrides||{}
+consthint=loadDevServerHint(this.options.cwd)
+
+// Without `--https` only `nuxt.config` knows whether https is wanted, and the
+// certificate options that come with it are not in the hint.
+if(overrides.httpsEnabled===undefined&&hint?.https){
+return
+}
+consthttpsEnabled=!!overrides.httpsEnabled
+
+consthasExplicitPort=overrides.port!==undefined&&overrides.port!==''
+constlistenOptions: ListenOptions={
+ ...overrides,
+port: hasExplicitPort ? overrides.port : hint?.port,
+hostname: overrides.hostname??hint?.hostname,
+baseURL: hint?.baseURL,
+https: httpsEnabled ? overrides.https : undefined,
+showURL: false,
+open: false,
+clipboard: false,
+tunnel: false,
+}
+
+try{
+this.#bound =awaitbindListener(this.handler,listenOptions)
+}
+catch(error){
+// An explicit port is the user's instruction, so its failure is a real
+// error; a guessed one may simply disagree with the config.
+if(hasExplicitPort){
+throwerror
+}
+debug('Could not bind the dev server before loading Nuxt:',error)
+return
+}
+
+this.listener=awaitcreateListener(this.#bound,listenOptions,{announce: false})
+
+constknowsScheme=overrides.httpsEnabled!==undefined||hint?.https===false
+if(overrides.open&&knowsScheme&&(hasExplicitPort||hint?.port===this.#bound.address.port)){
+this.#openedEagerly =true
+openBrowser(overrides.openURL ? resolveOpenURL(overrides.openURL,this.listener.url) : this.listener.url)
+}
+}
+
 async #createListener(): Promise<void>{
 if(!this.#currentNuxt){
 thrownewError('Nuxt must be loaded before creating listener')
 }
 
 constlistenOptions=this.#resolveListenOptions()
-this.listener=awaitlisten(this.handler,listenOptions)
+this.#persistDevServerHint(listenOptions.baseURL)
+
+if(this.#bound &&!matchesBoundTarget(this.#bound,listenOptions)){
+// Only loading screens have been served so far, so rebinding is safe.
+awaitthis.listener.close()
+this.#bound =undefined
+this.#openedEagerly =false
+}
+
+this.#bound ??=awaitbindListener(this.handler,listenOptions)
+this.listener=awaitcreateListener(this.#bound,{
+ ...listenOptions,
+open: listenOptions.open&&!this.#openedEagerly,
+})
 
 if(listenOptions.public){
 this.#currentNuxt.options.devServer.cors={origin: '*'}
@@ -563,7 +640,29 @@ export class NuxtDevServer extends EventEmitter<DevServerEventMap> {
 allowedHosts: urls.map(u=>newURL(u).hostname),
 },
 })
+constallowedHosts=this.#currentNuxt.options.vite.server?.allowedHosts
+if(Array.isArray(allowedHosts)){
+this.#currentNuxt.options.vite.server!.allowedHosts=dedupe(allowedHosts)
+}
+}
+}
+
+/**
+ * Record the address `nuxt.config` resolves to, so the next run can bind it
+ * before loading the config. CLI and env overrides are deliberately excluded:
+ * a one-off `--port` should not change where the next plain run binds.
+ */
+ #persistDevServerHint(baseURL?: string): void{
+constdevServer=this.#currentNuxt?.options.devServer
+if(!devServer){
+return
 }
+saveDevServerHint(this.options.cwd,{
+port: Number(devServer.port)||undefined,
+hostname: devServer.host||undefined,
+https: !!devServer.https,
+ baseURL,
+})
 }
 
  #resolveListenOptions(): ListenOptions{
@@ -871,6 +970,17 @@ function resolveDevServerHTTPS(certificate: false | ResolvedCertificate): NuxtOp
 return{key: certificate.key!,cert: certificate.cert!}
 }
 
+functiondedupe<T>(values: T[]): T[]{
+return[...newSet(values)]
+}
+
+/**
+ * Config the CLI injects on behalf of the live listener.
+ *
+ * Everything returned here is confined to `vite.server` and `devServer`, which
+ * Vite leaves out of its dependency optimiser hash. A port-derived or per-run
+ * value anywhere else would re-optimise dependencies on every start.
+ */
 functionresolveDevServerDefaults(listenOptions: {hostname?: string,https: boolean},urls: string[]=[]): Partial<NuxtConfig>{
 constdefaultConfig: Partial<NuxtConfig>={}
 
@@ -896,6 +1006,16 @@ function resolveDevServerDefaults(listenOptions: { hostname?: string, https: boo
 defaultConfig.devServer=defu(defaultConfig.devServer,{cors: {origin: portlessOrigins}})
 }
 
+// `defu` concatenates arrays, so the hostname and the listener urls overlap.
+constallowedHosts=defaultConfig.vite?.server?.allowedHosts
+if(Array.isArray(allowedHosts)){
+defaultConfig.vite!.server!.allowedHosts=dedupe(allowedHosts)
+}
+constcorsOrigin=defaultConfig.devServer?.cors?.origin
+if(Array.isArray(corsOrigin)){
+defaultConfig.devServer!.cors!.origin=dedupe(corsOrigin)
+}
+
 returndefaultConfig
 }