Debugging

VeloxKit exposes a Chrome DevTools Protocol (CDP) endpoint in dev mode. Use Chrome DevTools, VS Code, or any CDP-compatible debugger.

Enable the inspector

// veloxkit.config.ts
dev: {
  inspect: true,   // enables CDP on port 9229
}

Or pass the flag at startup:

npx veloxkit-cli dev --inspect

Connect Chrome DevTools

1. Open Chrome and navigate to chrome://inspect
2. Click Configure... and add localhost:9229
3. Your VeloxKit app appears under Remote Target
4. Click inspect

The full DevTools panel opens: Sources, Console, Memory, Performance.

Connect VS Code

Add a launch config to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to VeloxKit",
      "port": 9229,
      "restart": true,
      "localRoot": "${workspaceFolder}/src",
      "remoteRoot": "/"
    }
  ]
}

Start veloxkit dev --inspect, then press F5 in VS Code. Breakpoints work.

Console

console.log, console.warn, console.error, console.table all work and appear in both the terminal and the DevTools console.

console.log('debug value:', someObject)
console.table(db.query('SELECT * FROM notes LIMIT 5'))

React DevTools

React DevTools works via the CDP connection:

1. Install the standalone React DevTools: npm install -g react-devtools
2. Run react-devtools in a terminal
3. VeloxKit connects automatically when inspect: true

Component tree inspection, props, state, and hooks all work.

Performance profiling

The Performance panel in Chrome DevTools records JS execution, React renders, and native bridge calls. Look for:

• Long tasks (>50ms) in the main thread
• Unnecessary React re-renders (use React DevTools Profiler)
• Expensive db.query calls (they appear as native bridge calls)

Logging to file

import { fs } from 'veloxkit'
 
const logPath = fs.join(fs.appDataDir(), 'app.log')
 
export function log(message: string) {
  const line = `${new Date().toISOString()} ${message}\n`
  fs.appendText(logPath, line)  // fire-and-forget
}