feat(analyze,build,preview,dev): support builds without a server runtime

Author: danielroe

docs/preview.md

@@ -16,6 +16,8 @@ npx nuxt preview [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>
 
 The `preview` command starts a server to preview your Nuxt application after running the `build` command. `nuxt start` is the same command under another name. When running your application in production refer to the [Deployment section](/docs/getting-started/deployment).
 
+When the configured `server.builder` produces no server at all (a client-only build, for example), there is nothing to run: the static output is served directly instead, with unmatched paths falling back to the client entry so client-side routing works.
+
 Some Nitro presets do not produce a server that can be run locally. For those, the preset's own preview command is run instead, and the command tells you what it is running.
 
 ## Arguments

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

@@ -7,7 +7,7 @@ import { styleText } from 'node:util'
 import { note, taskLog } from '@clack/prompts'
 import { defineCommand } from 'citty'
 import { defu } from 'defu'
-import { join, relative, resolve } from 'pathe'
+import { join, relative } from 'pathe'
 import { serve } from 'srvx'
 
 import { resolveDotenvFileNames } from '../utils/args'
@@ -18,6 +18,7 @@ import { loadKit } from '../utils/kit'
 import { acquireLock, acquireOutputLock, formatLockError } from '../utils/lockfile'
 import { intro, logger, outro } from '../utils/logger'
 import { relativeToProcess, resolveRootDir } from '../utils/paths'
+import { resolveServerBuild } from '../utils/server-build'
 import { dotEnvArgs, extendsArgs, logLevelArgs, rootDirArgs } from './_shared'
 
 const NON_WORD_RE = /[^\w-]/g
@@ -80,7 +81,8 @@ export default defineCommand({
 
     const startTime = Date.now()
 
-    const { loadNuxt, buildNuxt } = await loadKit(cwd)
+    const kit = await loadKit(cwd)
+    const { loadNuxt, buildNuxt } = kit
 
     const nuxt = await loadNuxt({
       cwd,
@@ -133,7 +135,7 @@ export default defineCommand({
 
     const analyzeDir = nuxt.options.analyzeDir
     const buildDir = nuxt.options.buildDir
-    const outDir = resolve(nuxt.options.rootDir, nuxt.options.nitro.output?.dir || '.output')
+    const outDir = resolveServerBuild(kit, nuxt).dir
 
     nuxt.options.build.analyze = defu(nuxt.options.build.analyze, {
       filename: join(analyzeDir, 'client.html'),

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

@@ -18,6 +18,7 @@ import { intro, logger, outro } from '../utils/logger'
 import { resolveRootDir } from '../utils/paths'
 import { createPhaseReporter, formatPhaseBreakdown } from '../utils/phase-reporter'
 import { startCpuProfile, stopCpuProfile } from '../utils/profile'
+import { resolveServerBuild } from '../utils/server-build'
 import { dotEnvArgs, envNameArgs, extendsArgs, logLevelArgs, profileArgs, rootDirArgs } from './_shared'
 
 /** How often a phase repeats itself where there is no animated line. */
@@ -122,15 +123,18 @@ export default defineCommand({
       }
       releaseLocks.push(lock.release)
 
-      const nitro = kit.useNitro()
-      logger.info(`Nitro preset: ${styleText('cyan', nitro.options.preset)}`)
+      const serverBuild = resolveServerBuild(kit, nuxt)
+      if (serverBuild.target) {
+        logger.info(`${serverBuild.name === 'nitro' ? 'Nitro' : serverBuild.name} preset: ${styleText('cyan', serverBuild.target)}`)
+      }
 
-      const outputLock = acquireOutputLock(nuxt.options.rootDir, nitro.options.output.dir, {
+      const outputDir = serverBuild.dir
+      const outputLock = acquireOutputLock(nuxt.options.rootDir, outputDir, {
         command: 'build',
         cwd,
       })
       if (outputLock.existing) {
-        throw new ActionableError(formatLockError(outputLock.existing, { outputDir: relative(process.cwd(), nitro.options.output.dir) }))
+        throw new ActionableError(formatLockError(outputLock.existing, { outputDir: relative(process.cwd(), outputDir) }))
       }
       releaseLocks.push(outputLock.release)
 
@@ -153,7 +157,7 @@ export default defineCommand({
           logger.warn(`HTML content not prerendered because ${styleText('cyan', 'ssr: false')} was set.`)
           logger.info(`You can read more in ${styleText('cyan', 'https://nuxt.com/docs/getting-started/deployment#static-hosting')}.`)
         }
-        const dir = nitro.options.output.publicDir
+        const dir = serverBuild.publicDir
         const publicDir = dir ? relative(process.cwd(), dir) : '.output/public'
         outro(`✨ You can now deploy ${styleText('cyan', publicDir)} to any static hosting! ${styleText('gray', `(${formatDuration(Date.now() - start)})`)}`)
       }

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

@@ -14,8 +14,12 @@ import { loadKit } from '../utils/kit'
 import { logger, outro } from '../utils/logger'
 import { withPrependedPath } from '../utils/path-env'
 import { relativeToProcess, resolveRootDir } from '../utils/paths'
+import { getServerBuilderName } from '../utils/server-build'
+import { findStaticEntry, previewStaticOutput } from '../utils/static-preview'
 import { dotEnvArgs, envNameArgs, extendsArgs, logLevelArgs, rootDirArgs } from './_shared'
 
+const TRAILING_SLASH_RE = /\/$/
+
 const command = defineCommand({
   meta: {
     name: 'preview',
@@ -47,6 +51,8 @@ const command = defineCommand({
 
     let envLoaded = false
     let resolvedOutputDir: string | undefined
+    let resolvedPublicDir: string | undefined
+    let builderName: string | undefined
 
     try {
       const { loadNuxt } = await loadKit(cwd)
@@ -70,6 +76,14 @@ const command = defineCommand({
           ],
         },
       })
+      builderName = getServerBuilderName(nuxt)
+      // `nuxt.serverOutput` is only present in newer Nuxt; the `nitro:init` hook
+      // above covers older versions, which only ever built with Nitro.
+      const serverOutput = (nuxt as { serverOutput?: { dir: () => string, publicDir: () => string } }).serverOutput
+      if (serverOutput) {
+        resolvedOutputDir = resolve(serverOutput.dir(), 'nitro.json')
+        resolvedPublicDir = serverOutput.publicDir()
+      }
       await nuxt.close()
     }
     catch {}
@@ -79,9 +93,35 @@ const command = defineCommand({
       resolve(cwd, '.output', 'nitro.json'),
     ].filter((path): path is string => !!path))]
     const nitroJSONPath = nitroJSONPaths.find(p => existsSync(p))
+
+    const port = ctx.args.port
+      || process.env.NUXT_PORT
+      || process.env.NITRO_PORT
+      || process.env.PORT
+    const host = ctx.args.host
+      || process.env.NUXT_HOST
+      || process.env.NITRO_HOST
+      || process.env.HOST
+
     if (!nitroJSONPath) {
+      // A build with no server runtime leaves only static files, which the CLI
+      // can serve itself rather than reporting a missing server entry.
+      const publicDirs = [...new Set([
+        resolvedPublicDir,
+        resolve(cwd, '.output', 'public'),
+      ].filter((path): path is string => !!path))]
+      for (const dir of publicDirs) {
+        const entry = findStaticEntry(dir)
+        if (entry) {
+          logger.info(`This build has no server, so ${styleText('cyan', relativeToProcess(dir))} is being served statically.`)
+          const server = await previewStaticOutput({ dir, entry, port, hostname: host })
+          outro(`Previewing ${styleText('cyan', relativeToProcess(dir))} at ${styleText('cyan', server.url?.replace(TRAILING_SLASH_RE, '') || '')}`)
+          return
+        }
+      }
+
       logger.error(
-        `Cannot find ${styleText('cyan', 'nitro.json')}. Did you run ${styleText('cyan', 'nuxt build')} first? Search path:\n${nitroJSONPaths.join('\n')}`,
+        `Cannot find a build to preview${builderName ? ` for the ${styleText('cyan', builderName)} server builder` : ''}. Did you run ${styleText('cyan', 'nuxt build')} first? Search path:\n${[...nitroJSONPaths, ...publicDirs].join('\n')}`,
       )
       process.exit(1)
     }
@@ -145,15 +185,6 @@ const command = defineCommand({
       logger.error(`Cannot find ${missing.map(fileName => styleText('cyan', fileName)).join(', ')}.`)
     }
 
-    const port = ctx.args.port
-      || process.env.NUXT_PORT
-      || process.env.NITRO_PORT
-      || process.env.PORT
-    const host = ctx.args.host
-      || process.env.NUXT_HOST
-      || process.env.NITRO_HOST
-      || process.env.HOST
-
     outro(`Running ${styleText('cyan', previewCommand)} in ${styleText('cyan', relativeToProcess(outputPath))}`)
 
     const [command, ...commandArgs] = tokenizeArgs(previewCommand) as [string, ...string[]]

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

@@ -34,6 +34,7 @@ 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 { getServerBuilderName } from '../utils/server-build'
 import { renderError, renderErrorAnsi } from './error-lazy'
 import { isAllowedHost } from './host-check'
 import { bindListener, createListener, matchesBoundTarget, openBrowser, resolveOpenURL } from './listen'
@@ -1156,7 +1157,10 @@ export class NuxtDevServer extends EventEmitter<DevServerEventMap> {
     await Promise.all([typesPromise, kit.buildNuxt(this.#currentNuxt)])
 
     if (!this.#currentNuxt.server) {
-      throw new Error('Nitro server has not been initialized.')
+      throw new ActionableError(
+        `The ${styleText('cyan', getServerBuilderName(this.#currentNuxt))} server builder did not provide a dev server.\n`
+        + `       A ${styleText('cyan', 'server.builder')} must expose a \`handler\`, \`fetch\` or \`app\` on \`nuxt.server\` to be served by ${styleText('cyan', 'nuxt dev')}.`,
+      )
     }
 
     const distDir = join(this.#currentNuxt.options.buildDir, 'dist')

packages/nuxt-cli/src/utils/server-build.ts

@@ -0,0 +1,111 @@
+import type { Nuxt } from '@nuxt/schema'
+
+import { resolve } from 'pathe'
+
+/** Default output locations Nuxt uses when no server builder declares its own. */
+const DEFAULT_OUTPUT_DIR = '.output'
+const DEFAULT_PUBLIC_DIR = '.output/public'
+
+/**
+ * A server builder as the CLI needs to see it: a name to print, an optional
+ * deploy target within that builder, whether a server runtime exists, and where
+ * the build lands.
+ *
+ * `dir` and `publicDir` are getters, not values: a builder may still move its
+ * output after `nuxt.ready()` (Nitro resolves its preset, then `nitro:config`
+ * and `nitro.updateConfig()` can both change `output.dir`), so a snapshot taken
+ * before the build can be wrong by the time it is used.
+ */
+export interface ServerBuild {
+  /** The configured server builder, e.g. `nitro` or `vite`. */
+  name: string
+  /** A deploy target within that builder, e.g. a Nitro preset. */
+  target: string | undefined
+  /** Whether this build produced a server runtime at all. */
+  hasServer: boolean
+  /** Root of the build output. */
+  readonly dir: string
+  /** Static output served from the root of the deployment. */
+  readonly publicDir: string
+}
+
+/**
+ * Nuxt fields the CLI reads optimistically: they exist in recent Nuxt only, and
+ * the CLI supports a range of versions.
+ */
+interface MaybeModernNuxt extends Nuxt {
+  serverOutput?: { dir: () => string, publicDir: () => string }
+  options: Nuxt['options'] & { server?: { builder?: unknown } }
+}
+
+interface MaybeModernKit {
+  tryUseNitro?: () => NitroLike | undefined
+  useNitro: () => NitroLike
+}
+
+interface NitroLike {
+  options: { preset?: string, output?: { dir?: string, publicDir?: string } }
+}
+
+/**
+ * The Nitro instance for this build, or `undefined` when the configured server
+ * builder did not create one.
+ *
+ * `tryUseNitro` is only present in newer `@nuxt/kit`; on older versions
+ * `useNitro` throwing means the same thing.
+ */
+export function tryUseNitro(kit: MaybeModernKit): NitroLike | undefined {
+  if (typeof kit.tryUseNitro === 'function') {
+    return kit.tryUseNitro()
+  }
+  try {
+    return kit.useNitro()
+  }
+  catch {
+    return undefined
+  }
+}
+
+/**
+ * The name of the configured server builder, normalised for display: a module
+ * specifier such as `@nuxt/vite-server` reads as `vite`.
+ */
+export function getServerBuilderName(nuxt: Nuxt, hasServer?: boolean): string {
+  const builder = (nuxt as MaybeModernNuxt).options.server?.builder
+  if (typeof builder === 'string' && builder) {
+    return builder.replace(/^@nuxt\//, '').replace(/-server$/, '')
+  }
+  if (builder) {
+    return 'custom'
+  }
+  // Nuxt versions without `server.builder` only ever built with Nitro.
+  return hasServer === false ? 'unknown' : 'nitro'
+}
+
+/**
+ * Describe a loaded Nuxt instance's build in builder-agnostic terms.
+ *
+ * Output paths come from `nuxt.serverOutput` where available, falling back to
+ * the Nitro instance and then to Nuxt's defaults, so this works against Nuxt
+ * versions that predate either.
+ */
+export function resolveServerBuild(kit: MaybeModernKit, nuxt: Nuxt): ServerBuild {
+  const nitro = tryUseNitro(kit)
+  const serverOutput = (nuxt as MaybeModernNuxt).serverOutput
+
+  return {
+    name: getServerBuilderName(nuxt, !!nitro),
+    target: nitro?.options.preset,
+    hasServer: !!nitro,
+    get dir() {
+      return serverOutput?.dir()
+        ?? nitro?.options.output?.dir
+        ?? resolve(nuxt.options.rootDir, nuxt.options.nitro?.output?.dir || DEFAULT_OUTPUT_DIR)
+    },
+    get publicDir() {
+      return serverOutput?.publicDir()
+        ?? nitro?.options.output?.publicDir
+        ?? resolve(nuxt.options.rootDir, nuxt.options.nitro?.output?.publicDir || DEFAULT_PUBLIC_DIR)
+    },
+  }
+}

packages/nuxt-cli/src/utils/static-preview.ts

@@ -0,0 +1,41 @@
+import type { Server } from 'srvx'
+import { existsSync } from 'node:fs'
+
+import { readFile } from 'node:fs/promises'
+
+import { join } from 'pathe'
+import { serve } from 'srvx'
+import { staticMiddleware } from 'srvx/static'
+
+/** Files a client-only build uses as its entry, most specific first. */
+const SPA_FALLBACKS = ['200.html', 'index.html']
+
+/** Whether a directory looks like the static output of a client-only build. */
+export function findStaticEntry(dir: string): string | undefined {
+  return SPA_FALLBACKS.map(name => join(dir, name)).find(path => existsSync(path))
+}
+
+export interface StaticPreviewOptions {
+  dir: string
+  entry: string
+  port?: string
+  hostname?: string
+}
+
+/**
+ * Serve a build that has no server runtime: static files from disk, with every
+ * unmatched path answered by the client entry so client-side routing works.
+ */
+export async function previewStaticOutput(options: StaticPreviewOptions): Promise<Server> {
+  const server = serve({
+    port: options.port,
+    hostname: options.hostname,
+    middleware: [staticMiddleware({ dir: options.dir })],
+    async fetch() {
+      return new Response(await readFile(options.entry), {
+        headers: { 'content-type': 'text/html;charset=utf-8' },
+      })
+    },
+  })
+  return await server.ready()
+}

packages/nuxt-cli/test/unit/commands/build.spec.ts

@@ -2,6 +2,7 @@ import { runCommand } from 'citty'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 import build from '../../../src/commands/build'
+import { logger } from '../../../src/utils/logger'
 
 const mocks = vi.hoisted(() => ({
   acquireLock: vi.fn(),
@@ -36,7 +37,7 @@ vi.mock('../../../src/utils/lockfile', () => ({
   formatLockError: mocks.formatLockError,
 }))
 vi.mock('../../../src/utils/logger', () => ({
-  logger: { error: vi.fn(), info: vi.fn(), warn: vi.fn() },
+  logger: { error: vi.fn(), info: vi.fn(), warn: vi.fn(), message: vi.fn() },
   intro: vi.fn(),
   outro: vi.fn(),
 }))
@@ -145,4 +146,22 @@ describe('build', () => {
     expect(mocks.buildNuxt).not.toHaveBeenCalled()
     expect(mocks.releaseBuildDir).toHaveBeenCalledOnce()
   })
+
+  it('builds without a server, locking the default output directory', async () => {
+    mocks.buildNuxt.mockResolvedValue(undefined)
+    mocks.useNitro.mockImplementation(() => {
+      throw new Error('Nitro is not initialized!')
+    })
+    mocks.loadNuxt.mockResolvedValue({
+      hook: vi.fn(),
+      ready: vi.fn(),
+      options: { buildDir, rootDir: cwd, ssr: false, server: { builder: 'vite' } },
+    })
+
+    await run()
+
+    expect(mocks.acquireOutputLock).toHaveBeenCalledWith(cwd, outputDir, { command: 'build', cwd })
+    expect(mocks.buildNuxt).toHaveBeenCalled()
+    expect(logger.info).not.toHaveBeenCalledWith(expect.stringContaining('preset'))
+  })
 })