feat(cli): add --cpu-prof flag (#2046)

* feat(cli): add --cpu-prof flag

* chore: dynamically import profiler

* docs: add debugging guide

.changeset/little-falcons-unite.md

@@ -0,0 +1,10 @@
+---
+'@pandacss/node': patch
+'@pandacss/dev': patch
+---
+
+Add a `--cpu-prof` flag to `panda`, `panda cssgen`, `panda codegen` and `panda debug` commands This is useful for
+debugging performance issues in `panda` itself. This will generate a `panda-{command}-{timestamp}.cpuprofile` file in
+the current working directory, which can be opened in tools like [Speedscope](https://www.speedscope.app/)
+
+This is mostly intended for maintainers or can be asked by maintainers to help debug issues.

packages/cli/src/cli-main.ts

@@ -12,6 +12,7 @@ import {
   setupConfig,
   setupGitIgnore,
   setupPostcss,
+  startProfiling,
   writeAnalyzeJSON,
   type CssGenOptions,
 } from '@pandacss/node'
@@ -96,11 +97,17 @@ export async function main() {
     .option('-w, --watch', 'Watch files and rebuild')
     .option('-p, --poll', 'Use polling instead of filesystem events when watching')
     .option('--cwd <cwd>', 'Current working directory', { default: cwd })
+    .option('--cpu-prof', 'Generates a `.cpuprofile` to help debug performance issues')
     .action(async (flags: CodegenCommandFlags) => {
       const { silent, clean, config: configPath, watch, poll } = flags
 
       const cwd = resolve(flags.cwd ?? '')
 
+      let stopProfiling: Function = () => void 0
+      if (flags.cpuProf) {
+        stopProfiling = await startProfiling(cwd, 'codegen')
+      }
+
       if (silent) {
         logger.level = 'silent'
       }
@@ -126,6 +133,8 @@ export async function main() {
           { cwd, poll },
         )
       }
+
+      stopProfiling()
     })
 
   cli
@@ -143,11 +152,17 @@ export async function main() {
     .option('-p, --poll', 'Use polling instead of filesystem events when watching')
     .option('-o, --outfile [file]', "Output file for extracted css, default to './styled-system/styles.css'")
     .option('--cwd <cwd>', 'Current working directory', { default: cwd })
+    .option('--cpu-prof', 'Generates a `.cpuprofile` to help debug performance issues')
     .action(async (maybeGlob?: string, flags: CssGenCommandFlags = {}) => {
       const { silent, clean, config: configPath, outfile, watch, poll, minify, minimal, lightningcss } = flags
 
       const cwd = resolve(flags.cwd ?? '')
 
+      let stopProfiling: Function = () => void 0
+      if (flags.cpuProf) {
+        stopProfiling = await startProfiling(cwd, 'cssgen')
+      }
+
       const cssArtifact = ['preflight', 'tokens', 'static', 'global', 'keyframes'].find(
         (type) => type === maybeGlob,
       ) as CssArtifactType | undefined
@@ -206,6 +221,8 @@ export async function main() {
           }
         })
       }
+
+      stopProfiling()
     })
 
   cli
@@ -223,17 +240,24 @@ export async function main() {
     .option('--hash', 'Hash the generated classnames to make them shorter')
     .option('--lightningcss', 'Use `lightningcss` instead of `postcss` for css optimization.')
     .option('--emitTokensOnly', 'Whether to only emit the `tokens` directory')
+    .option('--cpu-prof', 'Generates a `.cpuprofile` to help debug performance issues')
     .action(async (files: string[], flags: MainCommandFlags) => {
       const { config: configPath, silent, ...rest } = flags
 
       const cwd = resolve(flags.cwd ?? '')
 
+      let stopProfiling: Function = () => void 0
+      if (flags.cpuProf) {
+        stopProfiling = await startProfiling(cwd, 'cli')
+      }
+
       if (silent) {
         logger.level = 'silent'
       }
 
       const config = compact({ include: files, ...rest, cwd })
       await generate(config, configPath)
+      stopProfiling()
     })
 
   cli
@@ -330,11 +354,17 @@ export async function main() {
     .option('--only-config', "Should only output the config file, default to 'false'")
     .option('-c, --config <path>', 'Path to panda config file')
     .option('--cwd <cwd>', 'Current working directory', { default: cwd })
+    .option('--cpu-prof', 'Generates a `.cpuprofile` to help debug performance issues')
     .action(async (maybeGlob?: string, flags: DebugCommandFlags = {}) => {
       const { silent, dry = false, outdir: outdirFlag, config: configPath } = flags ?? {}
 
       const cwd = resolve(flags.cwd!)
 
+      let stopProfiling: Function = () => void 0
+      if (flags.cpuProf) {
+        stopProfiling = await startProfiling(cwd, 'debug')
+      }
+
       if (silent) {
         logger.level = 'silent'
       }
@@ -348,6 +378,7 @@ export async function main() {
       const outdir = outdirFlag ?? join(...ctx.paths.root, 'debug')
 
       await debug(ctx, { outdir, dry, onlyConfig: flags.onlyConfig })
+      stopProfiling()
     })
 
   cli

packages/cli/src/types.ts

@@ -20,6 +20,7 @@ export interface CssGenCommandFlags {
   config?: string
   minify?: boolean
   lightningcss?: boolean
+  cpuProf?: boolean
 }
 
 export interface StudioCommandFlags extends Pick<Config, 'cwd'> {
@@ -45,6 +46,7 @@ export interface DebugCommandFlags {
   cwd?: string
   config?: string
   onlyConfig?: boolean
+  cpuProf?: boolean
 }
 
 export interface ShipCommandFlags {
@@ -61,6 +63,7 @@ export interface CodegenCommandFlags extends Pick<Config, 'cwd' | 'poll' | 'watc
   clean?: boolean
   silent?: boolean
   config?: string
+  cpuProf?: boolean
 }
 
 export interface MainCommandFlags extends Pick<Config, 'cwd' | 'poll' | 'watch'> {
@@ -74,4 +77,5 @@ export interface MainCommandFlags extends Pick<Config, 'cwd' | 'poll' | 'watch'>
   hash?: boolean
   emitTokensOnly?: boolean
   lightningcss?: boolean
+  cpuProf?: boolean
 }

packages/node/package.json

@@ -67,7 +67,8 @@
     "prettier": "^2.8.8",
     "ts-morph": "19.0.0",
     "ts-pattern": "5.0.5",
-    "tsconfck": "^2.1.2"
+    "tsconfck": "^2.1.2",
+    "v8-profiler-next": "^1.10.0"
   },
   "devDependencies": {
     "@types/fs-extra": "11.0.4",

packages/node/src/cpu-profile.ts

@@ -0,0 +1,33 @@
+import { logger } from '@pandacss/logger'
+import fs from 'fs'
+import path from 'path'
+
+export const startProfiling = async (cwd: string, prefix: string) => {
+  const v8Profiler = (await import('v8-profiler-next')).default
+  const date = new Date()
+  const timestamp = date.toISOString().replace(/[-:.]/g, '')
+  const title = `panda-${prefix}-${timestamp}`
+
+  // set generateType 1 to generate new format for cpuprofile
+  // to be compatible with cpuprofile parsing in vscode.
+  v8Profiler.setGenerateType(1)
+  v8Profiler.startProfiling(title, true)
+
+  const stopProfiling = () => {
+    const profile = v8Profiler.stopProfiling(title)
+    profile.export(function (error, result) {
+      if (error) {
+        console.error(error)
+        return
+      }
+      if (!result) return
+
+      const outfile = path.join(cwd, `${title}.cpuprofile`)
+      fs.writeFileSync(outfile, result)
+      logger.info('cpu-prof', outfile)
+      profile.delete()
+    })
+  }
+
+  return stopProfiling
+}

packages/node/src/index.ts

@@ -2,6 +2,7 @@ export { analyzeTokens, writeAnalyzeJSON } from './analyze-tokens'
 export { buildInfo } from './build-info'
 export { Builder } from './builder'
 export { codegen } from './codegen'
+export { startProfiling } from './cpu-profile'
 export { loadConfigAndCreateContext } from './config'
 export { PandaContext } from './create-context'
 export { cssgen, type CssGenOptions } from './cssgen'