Skip to main content
Debug JavaScript code with an interactive terminal-based debugger.
Very experimental WIP feature - functionality is limited and may change

​
Usage

porf debug [flags] script.js

​
Examples

porf debug script.js

​
Arguments

​
script.js
string
required
JavaScript or TypeScript file to debug

​
Debugger Interface

When launched, the debugger shows: 
porffor debugger: script.js@15    main->processData

   12 | function processData(arr) {
   13 |   let sum = 0;
   14 |   for (let i = 0; i < arr.length; i++) {
 ► 15 |     sum += arr[i];
   16 |   }
   17 |   return sum;
   18 | }

┌─ console ────────────────────────┐
│                                  │
│                                  │
│                                  │
└──────────────────────────────────┘

​
Interface Components

Shows current execution state: 
porffor debugger: script.js@15    main->processData
                  ^^^^^^^^ ^^      ^^^^^^^^^^^^^^^^
                  file    line     call stack

​
Code View

Displays source code with:
  • Line numbers
  • Current line indicator (►)
  • Surrounding context
  • Breakpoint markers

​
Console Panel

Shows program output:
  • console.log() output
  • console.error() output
  • Program results

​
Call Stack

Displays current function call chain: 
main->processData->helper

​
Debugger Commands

Continue execution until next breakpoint or completionShortcut: F5 or Continue button
Execute current line and pause at next lineShortcut: F10 or Step Over buttonDoes not step into function calls
Step into function callsShortcut: F11 or Step In buttonPauses at first line of called function
Continue until current function returnsShortcut: Shift+F11 or Step Out buttonResumes execution until function exit

​
Breakpoints

Set breakpoints during debugging:
  1. Navigate to desired line
  2. Toggle breakpoint
  3. Execution pauses when breakpoint is reached
Breakpoint functionality is implemented through the debugger UI. The exact mechanism is still being refined.

​
Example Session

1

Start debugger

porf debug script.js
Debugger pauses before first line
2

Step through code

Press Step Over to execute line by lineWatch variables and output in console panel
3

Step into function

Press Step In when on function callDebugger enters function body
4

Set breakpoint

Navigate to line and toggle breakpointPress Resume to run until breakpoint
5

Inspect state

View console output and call stackVerify program behavior

​
Code Instrumentation

The debugger works by:
  1. Parsing source: Reading your JavaScript/TypeScript
  2. Injecting hooks: Adding profiling calls at each line and function
  3. Executing: Running instrumented code
  4. Intercepting: Pausing at hooks and showing UI

​
TypeScript Support

porf debug --parse-types script.ts
porf debug -t script.ts
Debugger displays TypeScript source with type annotations.

​
Console Output

Program output appears in the console panel: 
console.log('Debug message');
console.error('Error message');
Both appear in the console section of the debugger UI.

​
Call Stack Navigation

The call stack shows function call hierarchy: 
main
main->processArray
main->processArray->sortItems
  • Deepest function is rightmost
  • Caller chain shows execution path
  • Updates as you step through code

​
Limitations

The debugger is very experimental and has significant limitations:
  • Limited variable inspection
  • No watch expressions
  • No conditional breakpoints
  • No call stack navigation (view only)
  • Terminal UI may have rendering issues
  • Not all JavaScript features supported
  • May crash or behave unexpectedly

​
When to Use Debug Mode

Step through unfamiliar code to understand execution order
Identify exactly where errors occur
Verify conditional branches and loops work correctly
View console output at specific points

​
Alternative Debugging

For more robust debugging: 
# Add console.log statements
porf script.js

​
Troubleshooting

​
Debugger won’t start

# Check if file exists
ls -l script.js

# Try running without debugger first
porf script.js

​
UI rendering issues

  • Resize terminal window
  • Try different terminal emulator
  • Check terminal supports ANSI colors

​
Breakpoints not working

  • Ensure line has executable code
  • Try stepping manually with Step Over
  • Check if feature is fully implemented

​
Crashes during debugging

  • Report issue on GitHub
  • Try simpler code first
  • Use alternative debugging methods

​
Debugger Architecture

Underneath, the debugger:
  1. Injects profiling hooks (profile1, profile2)
  2. Hooks fire before/after each line and function
  3. UI library (Byg) renders interface
  4. User input controls execution flow
  5. Console output is captured and displayed

​
Future Improvements

Planned enhancements:
  • Variable inspection and watch expressions
  • Conditional breakpoints
  • Call stack navigation
  • Memory inspection
  • Expression evaluation
  • Better UI/UX

​
Providing Feedback

Since this feature is experimental:
  1. Report bugs on GitHub
  2. Describe what works/doesn’t work
  3. Share use cases and needs
  4. Contribute improvements

​
Comparison with Other Debuggers

Featureporf debugNode.js debuggerBrowser DevTools
Interactive✓✓✓
BreakpointsLimited✓✓
Variable inspection✗✓✓
Watch expressions✗✓✓
Call stackView only✓✓
Terminal UI✓✓✗
MaturityExperimentalStableStable

Profile

Performance profiling

Run with -d

Debug compilation issues

REPL

Interactive exploration

Overview

All CLI commands

Build docs developers (and LLMs) love

Get started for freeTalk to us