fix(dev): warn when a browser cannot be opened and caption qr codes

Author: danielroe

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

@@ -250,14 +250,15 @@ async function resolvePort(requestedPort: number | undefined, hostname: string,
   return port
 }
 
-export async function printQRCode(url: string): Promise<void> {
+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)}` : ''
   // eslint-disable-next-line no-console
-  console.log(`\n${centerBlock(renderUnicodeCompact(url))}\n`)
+  console.log(`\n${centerBlock(renderUnicodeCompact(url))}${caption}\n`)
 }
 
 export async function copyURL(url: string): Promise<void> {
-  if (!isClipboardAvailable()) {
+  if (!hasDisplayServer()) {
     logger.warn('No clipboard is available in this environment.')
     return
   }
@@ -275,20 +276,21 @@ export async function copyURL(url: string): Promise<void> {
 const DISPLAY_REQUIRED_PLATFORMS = new Set<NodeJS.Platform>(['linux', 'freebsd', 'openbsd'])
 
 /**
- * Clipboard tools on Linux and BSD (`wl-copy`, `xsel`, `xclip`) need a display
- * server. Without one they exit before receiving any input, and the resulting
- * `EPIPE` escapes as an uncaught exception from inside the writing library.
+ * Whether a graphical session exists to receive a clipboard write or a browser
+ * launch. The tools involved on Linux and BSD (`wl-copy`, `xsel`, `xclip`,
+ * `xdg-open`) all need one, and fail in unhelpful ways without it: clipboard
+ * tools exit before reading their input, so the write fails with `EPIPE`.
  */
-function isClipboardAvailable(env: NodeJS.ProcessEnv = process.env): boolean {
+function hasDisplayServer(env: NodeJS.ProcessEnv = process.env): boolean {
   if (!DISPLAY_REQUIRED_PLATFORMS.has(process.platform)) {
     return true
   }
   return !!(env.WSL_DISTRO_NAME || env.WAYLAND_DISPLAY || env.DISPLAY)
 }
 
-function centerBlock(block: string): string {
+function centerBlock(block: string, blockWidth?: number): string {
   const lines = block.split('\n')
-  const width = Math.max(...lines.map(line => line.length))
+  const width = blockWidth ?? Math.max(...lines.map(line => line.length))
   const columns = Math.min(process.stdout.columns || 80, 80)
   const indent = ' '.repeat(Math.max(0, Math.floor((columns - width) / 2)))
   return lines.map(line => indent + line).join('\n')
@@ -342,16 +344,41 @@ export function resolveOpenCommand(
   return ['xdg-open', [url]]
 }
 
+/** How long a launcher has to fail before we assume the browser did open. */
+const BROWSER_LAUNCH_TIMEOUT_MS = 3000
+
 export function openBrowser(url: string): void {
   const resolved = resolveOpenCommand(url)
   if (!resolved) {
     return
   }
+  if (!hasDisplayServer()) {
+    logger.warn(`No browser is available in this environment. Open ${colors.cyan(url)} manually.`)
+    return
+  }
+
   const [command, args] = resolved
+  const onFailure = (error: unknown) => {
+    debug('Failed to open browser:', error)
+    logger.warn(`Could not open ${colors.cyan(url)} in a browser.`)
+  }
+
   try {
-    spawn(command, args, { stdio: 'ignore', detached: true }).on('error', error => debug('Failed to open browser:', error)).unref()
+    const child = spawn(command, args, { stdio: 'ignore', detached: true })
+    child.once('error', onFailure)
+    const onExit = (code: number | null) => {
+      if (code) {
+        onFailure(new Error(`\`${command}\` exited with code ${code}`))
+      }
+    }
+    child.once('exit', onExit)
+    // `BROWSER` may point at the browser itself rather than a launcher, in which
+    // case the process lives as long as the browser does and its eventual exit
+    // code says nothing about whether the URL opened.
+    setTimeout(() => child.off('exit', onExit), BROWSER_LAUNCH_TIMEOUT_MS).unref()
+    child.unref()
   }
   catch (error) {
-    debug('Failed to open browser:', error)
+    onFailure(error)
   }
 }

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

@@ -47,7 +47,7 @@ const shortcuts: Shortcut[] = [
   {
     keys: ['qr'],
     description: 'show a QR code for the server URL',
-    action: context => printQRCode(resolveShareableURL(context.listener)),
+    action: context => printQRCode(resolveShareableURL(context.listener), { showURL: true }),
   },
   {
     keys: ['copy'],

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

@@ -2,15 +2,19 @@ import type { Listener } from '../../src/dev/listen'
 
 import { networkInterfaces } from 'node:os'
 
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import { copyURL, getNetworkAddresses, listen, resolveOpenCommand } from '../../src/dev/listen'
+import { copyURL, getNetworkAddresses, listen, openBrowser, resolveOpenCommand } from '../../src/dev/listen'
 
 const writeText = vi.hoisted(() => vi.fn())
 
 vi.mock('tinyclip', () => ({ writeText }))
 
-const spawn = vi.hoisted(() => vi.fn((_command: string, _args: string[]) => ({ on: () => ({ unref: () => {} }) })))
+const spawn = vi.hoisted(() => vi.fn((_command: string, _args: string[]) => ({
+  once: () => {},
+  off: () => {},
+  unref: () => {},
+})))
 
 vi.mock('node:child_process', () => ({ spawn }))
 
@@ -21,6 +25,20 @@ vi.mock('node:os', () => ({
 
 const mocked = vi.mocked(networkInterfaces)
 
+const realPlatform = process.platform
+const realEnv = { ...process.env }
+
+/** Pretend to run on `platform`, with only the display variables in `env` set. */
+function stubEnvironment(platform: NodeJS.Platform, env: NodeJS.ProcessEnv = {}) {
+  Object.defineProperty(process, 'platform', { value: platform, configurable: true })
+  process.env = { ...realEnv, DISPLAY: undefined, WAYLAND_DISPLAY: undefined, WSL_DISTRO_NAME: undefined, ...env }
+}
+
+function restoreEnvironment() {
+  Object.defineProperty(process, 'platform', { value: realPlatform, configurable: true })
+  process.env = { ...realEnv }
+}
+
 describe('getNetworkAddresses', () => {
   it('should return external IPv4 addresses', () => {
     mocked.mockReturnValue({
@@ -76,7 +94,11 @@ describe('resolveOpenCommand', () => {
 describe('listen', () => {
   const listeners: Listener[] = []
 
+  // `openBrowser` refuses to spawn a launcher without a graphical session.
+  beforeEach(() => stubEnvironment(realPlatform, { DISPLAY: ':0' }))
+
   afterEach(async () => {
+    restoreEnvironment()
     await Promise.all(listeners.splice(0).map(listener => listener.close()))
   })
 
@@ -124,48 +146,62 @@ describe('listen', () => {
 })
 
 describe('copyURL', () => {
-  const platform = process.platform
-  const env = { ...process.env }
-
   afterEach(() => {
-    Object.defineProperty(process, 'platform', { value: platform, configurable: true })
-    process.env = { ...env }
+    restoreEnvironment()
     vi.clearAllMocks()
   })
 
-  function stubPlatform(value: NodeJS.Platform, overrides: NodeJS.ProcessEnv = {}) {
-    Object.defineProperty(process, 'platform', { value, configurable: true })
-    process.env = { ...env, DISPLAY: undefined, WAYLAND_DISPLAY: undefined, WSL_DISTRO_NAME: undefined, ...overrides }
-  }
-
   it('should skip copying without a display server on linux', async () => {
-    stubPlatform('linux')
+    stubEnvironment('linux')
 
     await copyURL('http://localhost:3000/')
 
     expect(writeText).not.toHaveBeenCalled()
   })
 
   it('should copy when a display server is available', async () => {
-    stubPlatform('linux', { DISPLAY: ':0' })
+    stubEnvironment('linux', { DISPLAY: ':0' })
 
     await copyURL('http://localhost:3000/')
 
     expect(writeText).toHaveBeenCalledWith('http://localhost:3000/')
   })
 
   it('should copy on platforms that do not need a display server', async () => {
-    stubPlatform('darwin')
+    stubEnvironment('darwin')
 
     await copyURL('http://localhost:3000/')
 
     expect(writeText).toHaveBeenCalledWith('http://localhost:3000/')
   })
 
   it('should warn rather than throw when copying fails', async () => {
-    stubPlatform('darwin')
+    stubEnvironment('darwin')
     writeText.mockRejectedValueOnce(new Error('no clipboard tool found'))
 
     await expect(copyURL('http://localhost:3000/')).resolves.toBeUndefined()
   })
 })
+
+describe('openBrowser', () => {
+  afterEach(() => {
+    restoreEnvironment()
+    vi.clearAllMocks()
+  })
+
+  it('should not spawn a launcher without a display server', () => {
+    stubEnvironment('linux')
+
+    openBrowser('http://localhost:3000/')
+
+    expect(spawn).not.toHaveBeenCalled()
+  })
+
+  it('should spawn a launcher when a display server is available', () => {
+    stubEnvironment('linux', { DISPLAY: ':0' })
+
+    openBrowser('http://localhost:3000/')
+
+    expect(spawn).toHaveBeenCalledWith('xdg-open', ['http://localhost:3000/'], expect.anything())
+  })
+})

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

@@ -100,7 +100,7 @@ describe('setupShortcuts', () => {
     const { press } = setup({ close })
 
     await press('qr')
-    await vi.waitFor(() => expect(printQRCode).toHaveBeenCalledWith('http://localhost:3000/'))
+    await vi.waitFor(() => expect(printQRCode).toHaveBeenCalledWith('http://localhost:3000/', { showURL: true }))
     expect(close).not.toHaveBeenCalled()
 
     await press('q')