feat(dev): add restart, url, qr and copy shortcuts

Author: danielroe

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

@@ -4,16 +4,16 @@ import type { DevListenOverrides } from '../dev/listen'
 import type { NuxtDevContext } from '../dev/utils'
 
 import process from 'node:process'
-import { createInterface } from 'node:readline'
 
 import { defineCommand } from 'citty'
 import { resolve } from 'pathe'
 import colors from 'picocolors'
-import { isBun, isCI, isTest } from 'std-env'
+import { isBun, isTest } from 'std-env'
 import { satisfies } from 'verkit'
 
 import { initialize } from '../dev'
 import { ForkPool } from '../dev/pool'
+import { setupShortcuts } from '../dev/shortcuts'
 import { debug, logger } from '../utils/logger'
 import { cwdArgs, dotEnvArgs, envNameArgs, extendsArgs, legacyRootDirArgs, logLevelArgs, profileArgs } from './_shared'
 
@@ -135,15 +135,15 @@ const command = defineCommand({
     const listenOverrides = resolveListenOverrides(ctx.args)
 
     // Start the initial dev server in-process with listener
-    const { listener, close, onRestart, onReady } = await initialize({ cwd, args: ctx.args }, {
+    const { listener, close, reload, onRestart, onReady } = await initialize({ cwd, args: ctx.args }, {
       data: ctx.data,
       listenOverrides,
       showBanner: true,
     })
 
     // Disable forking when profiling to capture all activity in one process
     if (!ctx.args.fork || ctx.args.profile) {
-      setupQuitShortcut(close, onReady)
+      setupShortcuts({ listener, close, onReady, restart: () => reload('Restart requested') })
       return {
         listener,
         close,
@@ -192,18 +192,20 @@ const command = defineCommand({
       })
     }
 
-    onRestart(async () => {
+    async function restart() {
       // Close the in-process dev server
       await close()
       await restartWithFork()
-    })
+    }
+
+    onRestart(restart)
 
     async function closeAll() {
       cleanupCurrentFork?.()
       await close()
     }
 
-    setupQuitShortcut(closeAll, onReady)
+    setupShortcuts({ listener, close: closeAll, onReady, restart })
 
     return {
       close: closeAll,
@@ -215,35 +217,6 @@ export default command
 
 // --- Internal ---
 
-function setupQuitShortcut(close: () => Promise<void>, onReady: (callback: (address: string) => void) => void) {
-  if (!process.stdin.isTTY || isCI || isTest) {
-    return
-  }
-
-  onReady(() => {
-    // eslint-disable-next-line no-console
-    console.log(`\n  ${colors.dim('press')} ${colors.bold('q + enter')} ${colors.dim('to quit')}\n`)
-  })
-
-  // No output stream is passed, so readline stays in non-terminal mode and
-  // does not intercept Ctrl-C or put stdin into raw mode
-  const rl = createInterface({ input: process.stdin })
-  rl.on('line', async (line) => {
-    if (!['q', 'quit', 'exit'].includes(line.trim().toLowerCase())) {
-      return
-    }
-    rl.close()
-    try {
-      await close()
-    }
-    catch (error) {
-      console.error(error)
-      process.exitCode = 1
-    }
-    process.exit()
-  })
-}
-
 type ArgsT = Exclude<
   Awaited<typeof command.args>,
   undefined | ((...args: unknown[]) => unknown)

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

@@ -49,6 +49,8 @@ const ipc = new IPC()
 interface InitializeReturn {
   listener: Listener
   close: () => Promise<void>
+  /** Reload Nuxt in place, keeping the current listener. */
+  reload: (reason?: string) => Promise<void>
   onReady: (callback: (address: string) => void) => void
   onRestart: (callback: (devServer: NuxtDevServer) => void) => void
 }
@@ -134,6 +136,7 @@ export async function initialize(devContext: NuxtDevContext, ctx: InitializeOpti
 
   return {
     listener: devServer.listener,
+    reload: (reason?: string) => devServer.load(true, reason),
     close: () => {
       closePromise ??= (async () => {
         devServer.closeWatchers()

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

@@ -50,11 +50,17 @@ export interface DevListenOverrides extends ListenOptions {
 
 export interface Listener {
   url: string
+  /** Explicit public URL, or the tunnel or portless URL when there is one. */
+  publicURL?: string
+  /** URL the startup QR code was (or would have been) rendered for. */
+  qrURL?: string
   address: AddressInfo
   server: HttpServer
   https: false | ResolvedCertificate
   close: () => Promise<void>
   getURLs: () => ListenURL[]
+  /** Reprint the URL block, optionally flagging which URL a QR code refers to. */
+  showURLs: (options?: { qr?: boolean }) => void
 }
 
 const ANY_HOSTS = new Set(['', '0.0.0.0', '::'])
@@ -160,47 +166,41 @@ export async function listen(handler: RequestListener, options: ListenOptions =
 
   const publicURL = options.publicURL || tunnel?.url || portlessShareURL || portlessURL
 
-  if (options.showURL !== false) {
-    const urls = getURLs()
-    const qrURL = options.qr === false
-      ? undefined
-      : publicURL
-        || urls.find(({ type }) => type === 'network')?.url
-        || (options.qr ? url : undefined)
-
-    if (qrURL) {
-      const { renderUnicodeCompact } = await import('uqr')
-      // eslint-disable-next-line no-console
-      console.log(`\n${centerBlock(renderUnicodeCompact(qrURL))}\n`)
-    }
+  const qrURL = options.qr === false
+    ? undefined
+    : publicURL
+      || getURLs().find(({ type }) => type === 'network')?.url
+      || (options.qr ? url : undefined)
 
+  function showURLs({ qr = false }: { qr?: boolean } = {}): void {
+    const urls = getURLs()
     const labels = { local: 'Local:', network: 'Network:', tunnel: 'Tunnel:', public: 'Public:' } as const
     const labelColors = { local: colors.green, network: colors.magenta, tunnel: colors.cyan, public: colors.magenta } as const
     const lines: string[] = []
     const line = (color: (text: string) => string, label: string, value: string, isQR: boolean) =>
       `  ${color('➜')} ${colors.bold(color(label.padEnd(10)))}${value}${isQR ? colors.gray(' [QR code]') : ''}`
     for (const { url: displayURL, type } of urls) {
-      lines.push(line(labelColors[type], labels[type], colors.cyan(displayURL), displayURL === qrURL))
+      lines.push(line(labelColors[type], labels[type], colors.cyan(displayURL), qr && displayURL === qrURL))
     }
     if (!anyHost && !tunnel && !portless.url) {
       lines.push(line(colors.magenta, 'Network:', colors.gray(`use ${colors.white('--host')} to expose`), false))
     }
     if (publicURL && publicURL !== url && !urls.some(entry => entry.url === publicURL)) {
-      lines.push(line(colors.magenta, 'Public:', colors.cyan(publicURL), publicURL === qrURL))
+      lines.push(line(colors.magenta, 'Public:', colors.cyan(publicURL), qr && publicURL === qrURL))
     }
     // eslint-disable-next-line no-console
-    console.log(`${qrURL ? '' : '\n'}${lines.join('\n')}\n`)
+    console.log(`${qr ? '' : '\n'}${lines.join('\n')}\n`)
   }
 
-  if (options.clipboard) {
-    try {
-      const { writeText } = await import('tinyclip')
-      await writeText(publicURL || url)
-      logger.info('URL copied to clipboard.')
-    }
-    catch (error) {
-      debug('Failed to copy URL to clipboard:', error)
+  if (options.showURL !== false) {
+    if (qrURL) {
+      await printQRCode(qrURL)
     }
+    showURLs({ qr: !!qrURL })
+  }
+
+  if (options.clipboard) {
+    await copyURL(publicURL || url)
   }
 
   if (options.open) {
@@ -209,10 +209,13 @@ export async function listen(handler: RequestListener, options: ListenOptions =
 
   return {
     url,
+    publicURL,
+    qrURL,
     address,
     server,
     https: certificate,
     getURLs,
+    showURLs,
     close: async () => {
       await tunnel?.close()
       return new Promise<void>((resolve, reject) => {
@@ -247,6 +250,24 @@ async function resolvePort(requestedPort: number | undefined, hostname: string,
   return port
 }
 
+export async function printQRCode(url: string): Promise<void> {
+  const { renderUnicodeCompact } = await import('uqr')
+  // eslint-disable-next-line no-console
+  console.log(`\n${centerBlock(renderUnicodeCompact(url))}\n`)
+}
+
+export async function copyURL(url: string): Promise<void> {
+  try {
+    const { writeText } = await import('tinyclip')
+    await writeText(url)
+    logger.info('URL copied to clipboard.')
+  }
+  catch (error) {
+    debug('Failed to copy URL to clipboard:', error)
+    logger.warn('Could not copy the URL to the clipboard.')
+  }
+}
+
 function centerBlock(block: string): string {
   const lines = block.split('\n')
   const width = Math.max(...lines.map(line => line.length))
@@ -303,7 +324,7 @@ export function resolveOpenCommand(
   return ['xdg-open', [url]]
 }
 
-function openBrowser(url: string): void {
+export function openBrowser(url: string): void {
   const resolved = resolveOpenCommand(url)
   if (!resolved) {
     return

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

@@ -0,0 +1,139 @@
+import type { Listener } from './listen'
+
+import process from 'node:process'
+import { createInterface } from 'node:readline'
+
+import colors from 'picocolors'
+import { isCI, isTest } from 'std-env'
+
+import { copyURL, openBrowser, printQRCode } from './listen'
+
+export interface ShortcutContext {
+  listener: Listener
+  close: () => Promise<void>
+  restart?: () => void | Promise<void>
+  onReady: (callback: (address: string) => void) => void
+}
+
+interface ActionContext extends ShortcutContext {
+  /** Stop reading shortcuts, so a quitting server does not keep stdin open. */
+  closeInput: () => void
+}
+
+interface Shortcut {
+  keys: string[]
+  description: string
+  isAvailable?: (context: ShortcutContext) => boolean
+  action: (context: ActionContext) => void | Promise<void>
+}
+
+const shortcuts: Shortcut[] = [
+  {
+    keys: ['r', 'restart'],
+    description: 'restart the dev server',
+    isAvailable: context => !!context.restart,
+    action: context => context.restart?.(),
+  },
+  {
+    keys: ['o', 'open'],
+    description: 'open in browser',
+    action: context => openBrowser(context.listener.url),
+  },
+  {
+    keys: ['u', 'urls'],
+    description: 'show server URLs',
+    action: context => context.listener.showURLs(),
+  },
+  {
+    keys: ['qr'],
+    description: 'show a QR code for the server URL',
+    action: context => printQRCode(resolveShareableURL(context.listener)),
+  },
+  {
+    keys: ['copy'],
+    description: 'copy the server URL to the clipboard',
+    action: context => copyURL(resolveShareableURL(context.listener)),
+  },
+  {
+    keys: ['c', 'clear'],
+    description: 'clear the console',
+    action: (context) => {
+      process.stdout.write('\u001B[2J\u001B[3J\u001B[H')
+      context.listener.showURLs()
+    },
+  },
+  {
+    keys: ['q', 'quit', 'exit'],
+    description: 'quit',
+    action: quit,
+  },
+  {
+    keys: ['h', 'help', '?'],
+    description: 'show this help',
+    action: printHelp,
+  },
+]
+
+/** The URL most likely to work on another device, for QR codes and sharing. */
+function resolveShareableURL(listener: Listener): string {
+  return listener.qrURL
+    || listener.publicURL
+    || listener.getURLs().find(({ type }) => type === 'network')?.url
+    || listener.url
+}
+
+async function quit(context: ActionContext): Promise<void> {
+  context.closeInput()
+  try {
+    await context.close()
+  }
+  catch (error) {
+    console.error(error)
+    process.exitCode = 1
+  }
+  process.exit()
+}
+
+function printHelp(context: ActionContext): void {
+  const lines = availableShortcuts(context).map(({ keys, description }) =>
+    `  ${colors.dim('press')} ${colors.bold(`${keys[0]} + enter`)} ${colors.dim(`to ${description}`)}`,
+  )
+  // eslint-disable-next-line no-console
+  console.log(`\n${lines.join('\n')}\n`)
+}
+
+function availableShortcuts(context: ShortcutContext): Shortcut[] {
+  return shortcuts.filter(shortcut => shortcut.isAvailable?.(context) !== false)
+}
+
+/**
+ * Bind `<command> + enter` shortcuts to stdin.
+ *
+ * No output stream is passed to readline, so it stays in non-terminal mode and
+ * does not intercept Ctrl-C or put stdin into raw mode.
+ */
+export function setupShortcuts(context: ShortcutContext): void {
+  if (!process.stdin.isTTY || isCI || isTest) {
+    return
+  }
+
+  context.onReady(() => {
+    // eslint-disable-next-line no-console
+    console.log(`\n  ${colors.dim('press')} ${colors.bold('h + enter')} ${colors.dim('to see available shortcuts')}\n`)
+  })
+
+  const rl = createInterface({ input: process.stdin })
+  rl.on('line', async (line) => {
+    const input = line.trim().toLowerCase()
+    const shortcut = availableShortcuts(context).find(({ keys }) => keys.includes(input))
+    if (!shortcut) {
+      return
+    }
+    try {
+      await shortcut.action({ ...context, closeInput: () => rl.close() })
+    }
+    catch (error) {
+      console.error(error)
+    }
+  })
+}