feat(dev): respect BROWSER env when opening browser

Author: danielroe

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

@@ -236,20 +236,50 @@ function centerBlock(block: string): string {
   return lines.map(line => indent + line).join('\n')
 }
 
-function openBrowser(url: string): void {
+/**
+ * Resolve the command that opens `url`, honouring the de facto `BROWSER` and
+ * `BROWSER_ARGS` environment variables (`BROWSER=none` disables opening).
+ */
+export function resolveOpenCommand(
+  url: string,
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): [command: string, args: string[]] | undefined {
+  const browser = env.BROWSER?.trim()
+  if (browser === 'none') {
+    return
+  }
+
+  if (browser) {
+    const browserArgs = env.BROWSER_ARGS?.trim().split(/\s+/).filter(Boolean) ?? []
+    return platform === 'darwin' && !browser.includes('/')
+      ? ['open', ['-a', browser, url, ...(browserArgs.length > 0 ? ['--args', ...browserArgs] : [])]]
+      : [browser, [...browserArgs, url]]
+  }
+
   // WSL reports itself as Linux but has no X server, so `xdg-open` fails there;
   // `cmd.exe` opens the browser on the Windows side instead. WSL1 spells the
   // release `Microsoft`, WSL2 `microsoft-standard-WSL2`.
-  const isWSL = process.platform === 'linux'
-    && (!!process.env.WSL_DISTRO_NAME || release().toLowerCase().includes('microsoft'))
-
-  const [command, args] = process.platform === 'darwin'
-    ? ['open', [url]]
-    // `cmd /c start` owns the arcane quoting rules; `""` is a dummy window title
-    // (otherwise `start` treats a quoted URL as one), and `&`/`^` need escaping.
-    : process.platform === 'win32' || isWSL
-      ? ['cmd.exe', ['/c', 'start', '""', url.replace(/[&^]/g, '^$&')]]
-      : ['xdg-open', [url]] satisfies [string, string[]]
+  const isWSL = platform === 'linux'
+    && (!!env.WSL_DISTRO_NAME || release().toLowerCase().includes('microsoft'))
+
+  if (platform === 'darwin') {
+    return ['open', [url]]
+  }
+  // `cmd /c start` owns the arcane quoting rules; `""` is a dummy window title
+  // (otherwise `start` treats a quoted URL as one), and `&`/`^` need escaping.
+  if (platform === 'win32' || isWSL) {
+    return ['cmd.exe', ['/c', 'start', '""', url.replace(/[&^]/g, '^$&')]]
+  }
+  return ['xdg-open', [url]]
+}
+
+function openBrowser(url: string): void {
+  const resolved = resolveOpenCommand(url)
+  if (!resolved) {
+    return
+  }
+  const [command, args] = resolved
   try {
     spawn(command, args, { stdio: 'ignore', detached: true }).on('error', error => debug('Failed to open browser:', error)).unref()
   }

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

@@ -2,7 +2,7 @@ import { networkInterfaces } from 'node:os'
 
 import { describe, expect, it, vi } from 'vitest'
 
-import { getNetworkAddresses } from '../../src/dev/listen'
+import { getNetworkAddresses, resolveOpenCommand } from '../../src/dev/listen'
 
 vi.mock('node:os', () => ({
   networkInterfaces: vi.fn(),
@@ -33,3 +33,32 @@ describe('getNetworkAddresses', () => {
     expect(getNetworkAddresses()).toEqual(['192.168.1.20'])
   })
 })
+
+describe('resolveOpenCommand', () => {
+  const url = 'http://localhost:3000/'
+
+  it('should use the platform default when `BROWSER` is unset', () => {
+    expect(resolveOpenCommand(url, 'darwin', {})).toEqual(['open', [url]])
+    expect(resolveOpenCommand(url, 'linux', {})).toEqual(['xdg-open', [url]])
+    expect(resolveOpenCommand(url, 'win32', {})).toEqual(['cmd.exe', ['/c', 'start', '""', url]])
+  })
+
+  it('should open via `cmd.exe` on WSL', () => {
+    expect(resolveOpenCommand(url, 'linux', { WSL_DISTRO_NAME: 'Ubuntu' })).toEqual(['cmd.exe', ['/c', 'start', '""', url]])
+  })
+
+  it('should not open anything for `BROWSER=none`', () => {
+    expect(resolveOpenCommand(url, 'linux', { BROWSER: 'none' })).toBeUndefined()
+  })
+
+  it('should respect `BROWSER` and `BROWSER_ARGS`', () => {
+    expect(resolveOpenCommand(url, 'linux', { BROWSER: 'firefox' })).toEqual(['firefox', [url]])
+    expect(resolveOpenCommand(url, 'linux', { BROWSER: 'firefox', BROWSER_ARGS: '--private-window' })).toEqual(['firefox', ['--private-window', url]])
+  })
+
+  it('should launch a named application with `open -a` on macOS', () => {
+    expect(resolveOpenCommand(url, 'darwin', { BROWSER: 'Firefox' })).toEqual(['open', ['-a', 'Firefox', url]])
+    expect(resolveOpenCommand(url, 'darwin', { BROWSER: 'Firefox', BROWSER_ARGS: '--private-window' })).toEqual(['open', ['-a', 'Firefox', url, '--args', '--private-window']])
+    expect(resolveOpenCommand(url, 'darwin', { BROWSER: '/usr/local/bin/firefox' })).toEqual(['/usr/local/bin/firefox', [url]])
+  })
+})