fix(analyze): guard builds and simplify serving

Author: danielroe

packages/nuxt-cli/package.json

@@ -92,7 +92,6 @@
     "@types/node": "^24.13.3",
     "giget": "^3.3.1",
     "h3": "^1.15.11",
-    "h3-next": "npm:h3@^2.0.1-rc.26",
     "jiti": "^2.7.0",
     "nitro": "^3.0.1-alpha.2",
     "nitropack": "^2.13.4",

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

@@ -7,13 +7,13 @@ import { styleText } from 'node:util'
 import { intro, note, outro, taskLog } from '@clack/prompts'
 import { defineCommand } from 'citty'
 import { defu } from 'defu'
-import { H3, lazyEventHandler } from 'h3-next'
-import { join } from 'pathe'
+import { join, relative, resolve } from 'pathe'
 import { serve } from 'srvx'
 
 import { overrideEnv } from '../utils/env'
 import { clearDir } from '../utils/fs'
 import { loadKit } from '../utils/kit'
+import { acquireLock, acquireOutputLock, formatLockError } from '../utils/lockfile'
 import { logger } from '../utils/logger'
 import { relativeToProcess, resolveRootDir } from '../utils/paths'
 import { dotEnvArgs, extendsArgs, logLevelArgs, rootDirArgs } from './_shared'
@@ -72,7 +72,7 @@ export default defineCommand({
 
     const cwd = resolveRootDir(ctx.args)
     const name = ctx.args.name || 'default'
-    const slug = name.trim().replace(NON_WORD_RE, '_')
+    const slug = name.trim().replace(NON_WORD_RE, '_') || 'default'
 
     intro(styleText('cyan', 'Analyzing bundle size...'))
 
@@ -131,62 +131,86 @@ export default defineCommand({
 
     const analyzeDir = nuxt.options.analyzeDir
     const buildDir = nuxt.options.buildDir
-    const outDir
-      = nuxt.options.nitro.output?.dir || join(nuxt.options.rootDir, '.output')
+    const outDir = resolve(nuxt.options.rootDir, nuxt.options.nitro.output?.dir || '.output')
 
     nuxt.options.build.analyze = defu(nuxt.options.build.analyze, {
       filename: join(analyzeDir, 'client.html'),
     })
 
-    const tasklog = taskLog({
-      title: 'Building Nuxt with analysis enabled',
-      retainLog: false,
-      limit: 1,
-    })
-
-    tasklog.message('Clearing analyze directory...')
-    await clearDir(analyzeDir)
-    tasklog.message('Building Nuxt...')
-    await buildNuxt(nuxt)
-    tasklog.success('Build complete')
+    const lockInfo = { command: 'analyze' as const, cwd }
+    const lock = acquireLock(buildDir, lockInfo)
+    if (lock.existing) {
+      logger.error(formatLockError(lock.existing))
+      throw new Error(`Another Nuxt ${lock.existing.command} is already running (PID ${lock.existing.pid}).`)
+    }
 
-    if (skippedPrerenderRoutes > 0) {
-      logger.info(`Skipped prerendering ${skippedPrerenderRoutes} route${skippedPrerenderRoutes === 1 ? '' : 's'}. Pass ${styleText('cyan', '--prerender')} to include assets emitted while prerendering.`)
+    const outputLock = acquireOutputLock(nuxt.options.rootDir, outDir, lockInfo)
+    if (outputLock.existing) {
+      lock.release()
+      logger.error(formatLockError(outputLock.existing))
+      throw new Error(`Another Nuxt build is already writing to ${relative(process.cwd(), outDir)} (PID ${outputLock.existing.pid}).`)
     }
 
-    const endTime = Date.now()
+    try {
+      const tasklog = taskLog({
+        title: 'Building Nuxt with analysis enabled',
+        retainLog: false,
+        limit: 1,
+      })
 
-    const meta: NuxtAnalyzeMeta = {
-      name,
-      slug,
-      startTime,
-      endTime,
-      analyzeDir,
-      buildDir,
-      outDir,
+      tasklog.message('Clearing analyze directory...')
+      await clearDir(analyzeDir)
+      tasklog.message('Building Nuxt...')
+      await buildNuxt(nuxt)
+      tasklog.success('Build complete')
+
+      if (skippedPrerenderRoutes > 0) {
+        logger.info(`Skipped prerendering ${skippedPrerenderRoutes} route${skippedPrerenderRoutes === 1 ? '' : 's'}. Pass ${styleText('cyan', '--prerender')} to include assets emitted while prerendering.`)
+      }
+
+      const meta: NuxtAnalyzeMeta = {
+        name,
+        slug,
+        startTime,
+        endTime: Date.now(),
+        analyzeDir,
+        buildDir,
+        outDir,
+      }
+
+      await nuxt.callHook('build:analyze:done', meta)
+      await fsp.writeFile(join(analyzeDir, 'meta.json'), JSON.stringify(meta, null, 2), 'utf-8')
+    }
+    finally {
+      outputLock.release()
+      lock.release()
     }
-
-    await nuxt.callHook('build:analyze:done', meta)
-    await fsp.writeFile(join(analyzeDir, 'meta.json'), JSON.stringify(meta, null, 2), 'utf-8')
 
     note(`${relativeToProcess(analyzeDir)}\n\nDo not deploy analyze results! Use ${styleText('cyan', 'nuxt build')} before deploying.`, 'Build location')
 
     if (ctx.args.serve !== false && !process.env.CI) {
-      const app = new H3()
-
-      const opts = { headers: { 'content-type': 'text/html' } }
-      const serveFile = (filePath: string) => lazyEventHandler(async () => {
-        const contents = await fsp.readFile(filePath, 'utf-8')
-        return () => new Response(contents, opts)
-      })
+      const headers = { 'content-type': 'text/html' }
+      const readReport = (name: string) => fsp.readFile(join(analyzeDir, name), 'utf8').catch(() => undefined)
+      const reports = new Map([
+        ['/client', await readReport('client.html')],
+        ['/nitro', await readReport('nitro.html')],
+      ])
 
       logger.step('Starting stats server...')
 
-      app.use('/client', serveFile(join(analyzeDir, 'client.html')))
-      app.use('/nitro', serveFile(join(analyzeDir, 'nitro.html')))
-      app.use(() => new Response(indexHtml, opts))
-
-      await serve(app).serve()
+      await serve({
+        hostname: process.env.HOST || 'localhost',
+        fetch(request) {
+          const pathname = new URL(request.url).pathname.replace(/\/$/, '')
+          if (reports.has(pathname)) {
+            const report = reports.get(pathname)
+            return report === undefined
+              ? new Response('This report was not generated by the analyze build.', { status: 404, headers })
+              : new Response(report, { headers })
+          }
+          return new Response(indexHtml, { headers })
+        },
+      }).ready()
     }
     else {
       outro('✨ Analysis build complete!')

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

@@ -8,7 +8,7 @@ import { isCI } from 'std-env'
 export interface LockInfo {
   pid: number
   startedAt: number
-  command: 'dev' | 'build'
+  command: 'dev' | 'build' | 'analyze'
   cwd: string
   /**
    * Whether the holder was started from a terminal a user is sitting at. Only

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

@@ -1,10 +1,10 @@
 import type { Nuxt } from '@nuxt/schema'
 
-import { mkdir, mkdtemp, rm } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
 
 import { runCommand } from 'citty'
+import { join } from 'pathe'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import analyze from '../../../src/commands/analyze'
@@ -24,22 +24,27 @@ function createHooks() {
   }
 }
 
-const { loadNuxt, buildNuxt } = vi.hoisted(() => ({
-  loadNuxt: vi.fn(),
+const { acquireLock, acquireOutputLock, buildNuxt, loadNuxt, releaseBuildLock, releaseOutputLock } = vi.hoisted(() => ({
+  acquireLock: vi.fn(),
+  acquireOutputLock: vi.fn(),
   buildNuxt: vi.fn(),
+  loadNuxt: vi.fn(),
+  releaseBuildLock: vi.fn(),
+  releaseOutputLock: vi.fn(),
 }))
 
 vi.mock('../../../src/utils/kit', () => ({
   loadKit: () => Promise.resolve({ loadNuxt, buildNuxt }),
 }))
 
+vi.mock('../../../src/utils/lockfile', () => ({
+  acquireLock,
+  acquireOutputLock,
+  formatLockError: vi.fn(() => 'locked'),
+}))
+
 let cwd: string
 
-/**
- * Runs the command against a stub Nuxt, driving the same sequence Nitro does:
- * route rules and explicit routes are gathered into a set, `prerender:routes`
- * gets a chance to change it, and `prerender.ignore` filters what is left.
- */
 async function runAnalyze({ args = [], routes = [] }: { args?: string[], routes?: string[] } = {}) {
   const nuxtHooks = createHooks()
   const prerenderRoutes = new Set(routes)
@@ -80,6 +85,8 @@ async function runAnalyze({ args = [], routes = [] }: { args?: string[], routes?
 describe('nuxt analyze command', () => {
   beforeEach(async () => {
     vi.clearAllMocks()
+    acquireLock.mockReturnValue({ release: releaseBuildLock })
+    acquireOutputLock.mockReturnValue({ release: releaseOutputLock })
     cwd = await mkdtemp(join(tmpdir(), 'nuxt-analyze-'))
   })
 
@@ -110,4 +117,45 @@ describe('nuxt analyze command', () => {
     expect(overrides.nitro?.prerender).toBeUndefined()
     expect(output).not.toContain('Skipped prerendering')
   })
+
+  it('should write metadata and fall back to a non-empty slug', async () => {
+    await runAnalyze({ args: ['--name=   '] })
+
+    const meta = JSON.parse(await readFile(join(cwd, 'analyze/meta.json'), 'utf8'))
+    expect(meta).toMatchObject({
+      name: '   ',
+      slug: 'default',
+      analyzeDir: join(cwd, 'analyze'),
+      buildDir: join(cwd, '.nuxt'),
+      outDir: join(cwd, '.output'),
+    })
+    expect(meta.endTime).toBeGreaterThanOrEqual(meta.startTime)
+  })
+
+  it('should lock build directories and release both locks', async () => {
+    await runAnalyze()
+
+    expect(acquireLock).toHaveBeenCalledWith(join(cwd, '.nuxt'), { command: 'analyze', cwd })
+    expect(acquireOutputLock).toHaveBeenCalledWith(cwd, join(cwd, '.output'), { command: 'analyze', cwd })
+    expect(releaseOutputLock).toHaveBeenCalledOnce()
+    expect(releaseBuildLock).toHaveBeenCalledOnce()
+  })
+
+  it('should release locks when the build fails', async () => {
+    buildNuxt.mockRejectedValueOnce(new Error('build failed'))
+
+    await expect(runAnalyze()).rejects.toThrow('build failed')
+    expect(releaseOutputLock).toHaveBeenCalledOnce()
+    expect(releaseBuildLock).toHaveBeenCalledOnce()
+  })
+
+  it('should release the build lock when the output is locked', async () => {
+    acquireOutputLock.mockReturnValueOnce({
+      existing: { command: 'build', pid: 42 },
+    })
+
+    await expect(runAnalyze()).rejects.toThrow('Another Nuxt build is already writing')
+    expect(buildNuxt).not.toHaveBeenCalled()
+    expect(releaseBuildLock).toHaveBeenCalledOnce()
+  })
 })

packages/nuxt-cli/tsdown.config.ts

@@ -12,7 +12,6 @@ export const packaging: PackagingContract = {
 
 export default defineCliConfig({
   entry: ['src/index.ts', 'src/dev/index.ts'],
-  // h3 is inlined as we have two different versions (+ rou3 is a transitive dep of h3-next)
-  deps: { onlyBundle: ['h3', 'rou3'], neverBundle: PARSER_PACKAGES },
+  deps: { onlyBundle: ['h3'], neverBundle: PARSER_PACKAGES },
   ...packaging,
 })