vercel__next.js/scripts/trace-cli-startup.js

#!/usr/bin/env node
/**
 * CLI Startup Tracer
 *
 * Uses the V8 Inspector API to trace module loading at CLI startup.
 * This helps identify which modules are being loaded eagerly.
 *
 * Usage:
 *   node scripts/trace-cli-startup.js [--command=dev|build|--help]
 */

const inspector = require('inspector')
const fs = require('fs')
const path = require('path')

const args = process.argv.slice(2)
const getArg = (name, defaultValue) => {
  const arg = args.find((a) => a.startsWith(`--${name}=`))
  return arg ? arg.split('=')[1] : defaultValue
}

const command = getArg('command', '--help')
const outputDir = path.join(process.cwd(), 'profiles')

if (!fs.existsSync(outputDir)) {
  fs.mkdirSync(outputDir, { recursive: true })
}

console.log('\x1b[34m=== Next.js CLI Startup Trace ===\x1b[0m')
console.log(`Command: next ${command}`)
console.log(`Output directory: ${outputDir}`)
console.log('')

// Start CPU profiling
const session = new inspector.Session()
session.connect()

// Track module loading via require hook
const Module = require('module')
const originalRequire = Module.prototype.require
const loadedModules = []
const moduleLoadTimes = []

Module.prototype.require = function (id) {
  const start = process.hrtime.bigint()
  const result = originalRequire.apply(this, arguments)
  const end = process.hrtime.bigint()
  const durationMs = Number(end - start) / 1e6

  // Get the resolved path
  let resolvedPath = id
  try {
    resolvedPath = require.resolve(id, { paths: [this.path || process.cwd()] })
  } catch {}

  // Filter to show only Next.js-related modules
  if (resolvedPath.includes('next/dist/') || resolvedPath.includes('@next/')) {
    const shortPath = resolvedPath.includes('next/dist/')
      ? resolvedPath.split('next/dist/')[1]
      : resolvedPath

    if (!loadedModules.includes(shortPath)) {
      loadedModules.push(shortPath)
      moduleLoadTimes.push({ module: shortPath, time: durationMs })
    }
  }

  return result
}

// Save original process.exit and intercept to prevent CLI from exiting mid-profile
const originalExit = process.exit
process.exit = () => {
  // Don't actually exit during profiling - we want to capture the full profile
}

// Start profiling
session.post('Profiler.enable', () => {
  session.post('Profiler.start', () => {
    console.log('Starting CLI with profiling...')
    console.log('')

    const startTime = process.hrtime.bigint()

    // Load the CLI
    try {
      process.argv = [process.argv[0], 'next', command]
      require('../packages/next/dist/bin/next')
    } catch (e) {
      // Expected - CLI might throw
    }

    const endTime = process.hrtime.bigint()
    const totalMs = Number(endTime - startTime) / 1e6

    // Stop profiling and save
    session.post('Profiler.stop', (err, { profile }) => {
      if (err) {
        console.error('Error stopping profiler:', err)
      } else {
        const profilePath = path.join(
          outputDir,
          `cli-startup-${Date.now()}.cpuprofile`
        )
        fs.writeFileSync(profilePath, JSON.stringify(profile))
        console.log(`\x1b[32mProfile saved:\x1b[0m ${profilePath}`)
      }

      // Print results
      console.log('')
      console.log(`\x1b[32mTotal startup time:\x1b[0m ${totalMs.toFixed(2)}ms`)
      console.log('')
      console.log(`\x1b[33mModules loaded (${loadedModules.length}):\x1b[0m`)
      console.log('='.repeat(70))

      // Sort by load time
      moduleLoadTimes.sort((a, b) => b.time - a.time)
      moduleLoadTimes.slice(0, 30).forEach((m, i) => {
        const timeStr =
          m.time > 1
            ? `${m.time.toFixed(1)}ms`
            : `${(m.time * 1000).toFixed(0)}μs`
        console.log(`${String(i + 1).padStart(2)}. ${m.module} (${timeStr})`)
      })

      console.log('')
      console.log(`\x1b[33mAll loaded modules:\x1b[0m`)
      console.log(loadedModules.join('\n'))

      // Restore original require
      Module.prototype.require = originalRequire

      session.disconnect()

      // Exit cleanly now that profiling is complete
      originalExit(0)
    })
  })
})