next.js/scripts/profile-next-dev-boot.js

#!/usr/bin/env node
/**
 * Next.js CPU Profile Script
 *
 * Generates CPU profiles for Next.js startup and dev server boot.
 *
 * Usage:
 *   node scripts/profile-next-dev-boot.js [options]
 *
 * Options:
 *   --test-dir=PATH     Test project directory (default: /private/tmp/next-boot-test)
 *   --output-dir=PATH   Output directory for profiles (default: ./profiles)
 *   --turbopack         Use Turbopack (default)
 *   --webpack           Use Webpack
 *   --duration=MS       How long to profile after ready (default: 1000)
 *   --cli               Profile just the CLI entry point (runs next --help)
 *
 * Output files:
 *   - dev-turbopack-YYYY-MM-DDTHH-MM-SS.cpuprofile
 *   - cli-turbopack-YYYY-MM-DDTHH-MM-SS.cpuprofile
 *
 * The profile can be loaded in:
 *   - Chrome DevTools (Performance tab -> Load profile)
 *   - VS Code (JavaScript Profile Visualizer extension)
 *   - https://www.speedscope.app/
 *
 * Note: Currently profiles the parent process only. For child process profiling,
 * additional Next.js changes are needed (see future PRs).
 */

const { spawn, execSync } = require('child_process')
const path = require('path')
const fs = require('fs')

// Parse arguments
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 hasFlag = (name) => args.includes(`--${name}`)

const testDir = getArg('test-dir', '/private/tmp/next-boot-test')
const baseOutputDir =
  getArg('output-dir', null) || path.join(process.cwd(), 'profiles')
const useWebpack = hasFlag('webpack')
const duration = parseInt(getArg('duration', '1000'), 10)
const profileCli = hasFlag('cli')
const bundlerFlag = useWebpack ? '--webpack' : '--turbopack'

// Generate meaningful profile names
const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
const bundlerName = useWebpack ? 'webpack' : 'turbopack'
const profileType = profileCli ? 'cli' : 'dev'
const outputDir = baseOutputDir
const profileName = `${profileType}-${bundlerName}-${timestamp}`

const nextDir = path.join(__dirname, '..', 'packages', 'next')
const nextBin = path.join(nextDir, 'dist/bin/next')

if (profileCli) {
  console.log('\x1b[34m=== Next.js CLI Entry Point Profile ===\x1b[0m')
} else {
  console.log('\x1b[34m=== Next.js Dev Server CPU Profile ===\x1b[0m')
  console.log(`Test directory: ${testDir}`)
  console.log(`Bundler: ${useWebpack ? 'Webpack' : 'Turbopack'}`)
}
console.log(`Output directory: ${outputDir}`)
console.log('')

// Verify test directory (only for dev server profiling)
if (!profileCli && !fs.existsSync(testDir)) {
  console.error(
    `\x1b[31mError: Test directory does not exist: ${testDir}\x1b[0m`
  )
  process.exit(1)
}

// Create output directory
if (!fs.existsSync(outputDir)) {
  fs.mkdirSync(outputDir, { recursive: true })
}

// Kill existing processes
function killNextDev() {
  try {
    execSync('pkill -f "next dev"', { stdio: 'ignore' })
  } catch {}
}

async function runProfile() {
  killNextDev()
  await new Promise((r) => setTimeout(r, 500))

  // Clean .next directory
  const nextCache = path.join(testDir, '.next')
  if (fs.existsSync(nextCache)) {
    fs.rmSync(nextCache, { recursive: true, force: true })
  }

  console.log('Starting dev server with CPU profiling...')
  console.log('(Profile will be saved after server is ready)')
  console.log('')

  return new Promise((resolve, reject) => {
    let resolved = false

    // Profile the parent process with --cpu-prof
    const spawnArgs = [
      process.execPath,
      [
        '--cpu-prof',
        `--cpu-prof-dir=${outputDir}`,
        `--cpu-prof-name=${profileName}`,
        nextBin,
        'dev',
        bundlerFlag,
      ],
    ]

    const child = spawn(spawnArgs[0], spawnArgs[1], {
      cwd: testDir,
      stdio: ['ignore', 'pipe', 'pipe'],
      env: { ...process.env, FORCE_COLOR: '0' },
    })

    let output = ''

    const onData = (data) => {
      const text = data.toString()
      output += text
      process.stdout.write(text)

      // Wait for "Ready in Xms"
      if (output.includes('Ready in') && !resolved) {
        resolved = true
        console.log('')
        console.log(
          `\x1b[33mServer ready, profiling for ${duration}ms more...\x1b[0m`
        )

        // Wait a bit then stop
        setTimeout(() => {
          console.log('Stopping server and saving profile...')
          child.kill('SIGINT')
        }, duration)
      }
    }

    child.stdout.on('data', onData)
    child.stderr.on('data', onData)

    child.on('close', (code) => {
      killNextDev()

      // Wait a moment for profile files to be written
      setTimeout(() => {
        // Find and rename profiles matching our name pattern
        // --cpu-prof-name creates files without extension
        const files = fs.readdirSync(outputDir)
        const rawFiles = files.filter(
          (f) => f.startsWith(profileName) && !f.endsWith('.cpuprofile')
        )

        // Rename raw files to have .cpuprofile extension
        rawFiles.forEach((f) => {
          const oldPath = path.join(outputDir, f)
          const newPath = path.join(outputDir, `${f}.cpuprofile`)
          fs.renameSync(oldPath, newPath)
        })

        // Now find all .cpuprofile files
        const profileFiles = fs
          .readdirSync(outputDir)
          .filter((f) => f.startsWith(profileName) && f.endsWith('.cpuprofile'))
        const profiles = profileFiles
          .map((f) => ({
            name: f,
            path: path.join(outputDir, f),
            size: fs.statSync(path.join(outputDir, f)).size,
          }))
          .filter((p) => p.size > 0)
          .sort((a, b) => b.size - a.size)

        if (profiles.length > 0) {
          console.log('')
          console.log(`\x1b[32mProfile(s) saved:\x1b[0m`)
          profiles.forEach((p, i) => {
            const sizeKB = Math.round(p.size / 1024)
            console.log(`  ${i + 1}. ${p.path} (${sizeKB} KB)`)
          })
          console.log('')
          console.log('To view the profile:')
          console.log('  1. Open Chrome DevTools -> Performance tab')
          console.log('  2. Click "Load profile" and select the file')
          console.log('  3. Or use https://www.speedscope.app/')
          console.log('')
          console.log(
            '\x1b[33mTip:\x1b[0m The largest profile is usually the child process (server worker)'
          )
          resolve(profiles[0].path)
        } else {
          console.log('')
          console.log(
            '\x1b[33mNo profiles found. Trying alternative method...\x1b[0m'
          )
          console.log('')
          console.log(
            'To profile the child process, modify next-dev.ts to add profiling flags.'
          )
          console.log(
            'Or use: node --cpu-prof --cpu-prof-dir=./profiles ./dist/bin/next dev'
          )
          reject(new Error('Profile file not found'))
        }
      }, 500)
    })

    child.on('error', reject)

    // Timeout
    setTimeout(() => {
      if (!resolved) {
        child.kill('SIGKILL')
        reject(new Error('Timeout waiting for server'))
      }
    }, 120000)
  })
}

async function runCliProfile() {
  console.log('Profiling CLI entry point (next --help)...')
  console.log('')

  return new Promise((resolve, reject) => {
    const child = spawn(
      process.execPath,
      [
        '--cpu-prof',
        `--cpu-prof-dir=${outputDir}`,
        `--cpu-prof-name=${profileName}`,
        nextBin,
        '--help',
      ],
      {
        cwd: process.cwd(),
        stdio: ['ignore', 'pipe', 'pipe'],
        env: { ...process.env, FORCE_COLOR: '0' },
      }
    )

    child.stdout.on('data', () => {})
    child.stderr.on('data', () => {})

    child.on('close', (code) => {
      // Wait for profile to be written
      setTimeout(() => {
        // --cpu-prof-name creates files without extension, rename to .cpuprofile
        const rawFile = path.join(outputDir, profileName)
        const finalFile = path.join(outputDir, `${profileName}.cpuprofile`)

        if (fs.existsSync(rawFile)) {
          fs.renameSync(rawFile, finalFile)
          const size = fs.statSync(finalFile).size
          console.log(`\x1b[32mProfile saved:\x1b[0m`)
          console.log(`  ${finalFile} (${Math.round(size / 1024)} KB)`)
          console.log('')
          console.log('To view the profile:')
          console.log('  1. Open Chrome DevTools -> Performance tab')
          console.log('  2. Click "Load profile" and select the file')
          console.log('  3. Or use https://www.speedscope.app/')
          console.log('')
          console.log(
            '\x1b[33mTip:\x1b[0m Look for heavy modules loaded at startup'
          )
          resolve(finalFile)
        } else if (fs.existsSync(finalFile)) {
          const size = fs.statSync(finalFile).size
          console.log(`\x1b[32mProfile saved:\x1b[0m`)
          console.log(`  ${finalFile} (${Math.round(size / 1024)} KB)`)
          resolve(finalFile)
        } else {
          reject(new Error('Profile file not found'))
        }
      }, 500)
    })

    child.on('error', reject)
  })
}

// Main execution
const main = profileCli ? runCliProfile : runProfile

main().catch((err) => {
  console.error('\x1b[31mError:\x1b[0m', err.message)
  if (!profileCli) killNextDev()
  process.exit(1)
})