DOCSEARCHbyAlgolia
Submit Docs

Console Ninja Documentation

repository·main·Indexed 19 days ago

https://github.com/wallabyjs/console-ninja

A VS Code extension that displays runtime logs and errors from browsers or Node.js directly in the editor. It supports a wide range of technologies including Vite, Webpack, Next.js, Remix, Astro, Nuxt, and React Native with Expo. Features include Community and PRO editions with capabilities such as Logpoints, Network logging, File Code Coverage, GitHub Copilot integration, and an MCP server for LLM agents.

Tokens
2.7K
Snippets
1
Records
15
Agent score
18%

What's inside Console Ninja

  1. What is Console Ninja

    main
    Console Ninja is a VS Code extension that displays console.log output and runtime errors directly in your editor from your running browser or Node.js application. It eliminates the need to context-switch between your code and the browser dev tools console or terminal by connecting log values directly to your source code in an ergonomic way.

  2. How Console Ninja works and how to stop it

    main

    Console Ninja integrates with locally installed build tools by patching your locally installed node_modules. It inspects and adjusts your code before it reaches the runtime (browser or Node.js) to capture logs and errors without changing execution behavior.

    To stop Console Ninja and remove all patches, use the Pause command in your editor.

    Troubleshooting after stopping: If you experience runtime issues (like WebSocket errors in the browser) after pausing, clear your build tool's cache by running one of the following commands depending on your stack:

    • rm -rf node_modules/.cache
    • rm -rf .next
    • rm -rf .angular

    If issues persist, re-installing node_modules will force the build tool to create a fresh cache.

  3. Security and Production Safety

    main

    Console Ninja detects production mode via CLI flags and process environment variables. In production mode, it will not modify your application code.

    Safety Recommendation: If you are running production builds locally and might share/deploy those builds, run the Console Ninja Pause command in your editor before running your build to ensure no instrumented code is included in your production artifacts.

    Data Privacy: Runtime data is sent only to a localhost hosted WebSocket server in your local editor. Data is never sent outside of your local machine.

  4. Use Function and Class logpoints

    main

    Console Ninja provides specialized logpoints for entire structures:

    • Function logpoints: Place a breakpoint (F9) on a line where a function/method is defined. This logs every line of the function and its argument values without modifying the body. You can use an inline breakpoint (Shift + F9) to override specific values within the function.
    • Class logpoints: Place a breakpoint (F9) on a line where a class is defined. This logs every line of all functions within that class.

    Code Coverage: Function logpoints also collect accumulated code coverage, displayed via gutter indicators:

    • Gray: Not executed yet.
    • Yellow: Partially executed.
    • Green: Executed at least once.
    • Red: Source of an error or in an error stack.

  5. Compare Console Ninja Community and PRO editions

    main

    Console Ninja is available in two feature sets:

    • Community Edition: Free to use and will always be free. It includes fundamental features like displaying console.log output and runtime errors directly in the editor, and showing recorded logs/errors in the Log Viewer.
    • PRO Edition: A paid subscription that includes all Community features plus advanced debugging capabilities such as Log Maps, Logpoints, Network logging, File Code Coverage, and GitHub Copilot integration.

    You can switch between feature sets in the extension settings or request a PRO trial using the Console Ninja: Manage License command in VS Code.

  6. Compare Console Ninja with other tools

    main

    Console Ninja vs Quokka.js

    • Quokka.js: Runs code in an isolated playground (scratch files or existing files) as a self-contained program.
    • Console Ninja: Runs within your application (started by your dev server or test runner) to debug end-to-end scenarios in your actual running app.

    Console Ninja vs Wallaby.js

    • Wallaby.js: Focuses on running tests (Jest, Vitest, Mocha, etc.) immediately as you type, providing inline coverage and time-travel debugging. It handles test results specifically.
    • Console Ninja: Displays logs from supported test runner CLIs, but does not handle the test errors themselves (as those are managed by the test runner).

    Console Ninja vs Error Lens

    • Error Lens: Displays static code analysis errors (linter violations, TypeScript type errors) from the VS Code Problems window.
    • Console Ninja: Displays runtime logs and errors that occur while your application is executing.

  7. Use Logpoints to capture values without modifying code

    main

    Logpoints allow you to log the value of any expression in your code without inserting console.log statements. This is achieved by placing a VS Code breakpoint on a line. When Console Ninja is running (and the VS Code debugger is not), the breakpoint acts as a logpoint, displaying the value next to your code and in the log viewer.

    • Standard Logpoint: Place a breakpoint (F9) on a line.
    • Inline Logpoint: Place an inline breakpoint (Shift + F9) near/inside a specific expression (e.g., inside an arrow function or a JSX expression) to be more precise about what to log.

    A ⚡️ indicator appears at the line once Console Ninja is ready to output values. If no indicator appears, the location may not contain executable JS/TS code.

    To remove logpoints in bulk, use the Console Ninja: Remove all Breakpoints in File command or the Remove All Breakpoints command.

    // Example: Using Shift + F9 to log an expression in the middle of a chain
a.b().c(); // Place inline breakpoint near b() to log its result

  8. Integrate Console Ninja with GitHub Copilot

    main

    Console Ninja equips GitHub Copilot with application context (errors, stack traces, logs) for smarter debugging.

    How to use:

    1. Install GitHub Copilot and restart VS Code.
    2. Click the Investigate with AI icon next to an application error (available in hover tooltips, the editor lightbulb, or the Log Viewer).
    3. Alternatively, use the Console Ninja: Investigate with AI command from the command palette.

    Console Ninja registers @console-ninja as a Copilot chat participant. The AI can request additional context (source code, logs) which Console Ninja will prompt you to allow by default.

  9. Use Tracepoints and Timepoints

    main

    Capture execution flow and performance without code changes:

    • Tracepoints: Use the Add Tracepoint command on any line/column (even inside expressions). When reached, Console Ninja logs the current stack trace and the value of the expression at that position.
    • Timepoints: Use the Add Timepoint command to mark a start and end point. Console Ninja will display the execution time next to the end timepoint and in the log viewer.

  10. Setup Console Ninja MCP Server

    main

    The Model Context Protocol (MCP) server allows LLM agents (Cursor, Windsurf, Claude Code, etc.) to access your app runtime logs and errors. While Copilot Agent mode works out-of-the-box, other clients require manual configuration.

    Copilot (VS Code settings.json)

    MacOS/Linux:

    {
  "mcp": {
    "servers": {
      "console-ninja": {
        "command": "npx",
        "args": ["-y", "-c", "node ~/.console-ninja/mcp/"]
      }
    }
  }
}

    Windows:

    {
  "mcp": {
    "servers": {
      "console-ninja": {
        "command": "cmd.exe",
        "args": ["/c", "node", "%USERPROFILE%/.console-ninja/mcp/"]
      }
    }
  }
}

    Cursor

    All projects (modify ~/.cursor/mcp.json):

    {
  "mcpServers": {
    "console-ninja": {
      "command": "node",
      "args": ["~/.console-ninja/mcp/"]
    }
  }
}

    Claude Code

    Run in terminal:

    claude mcp add console-ninja -s project -- npx "-y" "-c" "node ~/.console-ninja/mcp"

    Note: If you get a spawn node error, use the full path to your node executable.

    Windsurf

    Run Windsurf: MCP Configuration Panel and add the following: MacOS/Linux:

    {
  "mcpServers": {
    "console-ninja": {
      "command": "npx",
      "args": ["-y", "-c", "node ~/.console-ninja/mcp/"]
    }
  }
}

    Windows:

    {
  "mcpServers": {
    "console-ninja": {
      "command": "cmd.exe",
      "args": ["/c", "node", "%USERPROFILE%/.console-ninja/mcp/"]
    }
  }
}

  11. Visualize runtime data with Interactive Value Graphs

    main

    Complex runtime values (objects or arrays) can be visualized as interactive, structured graphs directly in your editor.

    How to use:

    1. Run your code.
    2. Hover over a complex value in the editor or access it via the Log Viewer context menu.
    3. Click the graph icon to open the graph view.

    Interactivity:

    • Zoom/Pan: Use the mouse wheel (hold Ctrl/Command to scroll) and click-and-drag to pan.
    • Expand/Collapse: Click on property values to explore nested structures.
    • Fit View: Click the Fit View icon to re-center the graph.
    • Node Menu: Use the vertical ellipses icon on a node to see the full property path and copy the path or value to the clipboard.

  12. Configure allowed hosts for Console Ninja

    main

    By default, Console Ninja instrumentation only works if the app host is 127.0.0.1, localhost, or one of your network adapter's IPv4 addresses. If you are accessing your app from a different hostname, you must configure the console-ninja.allowedHosts VS Code setting.

    Pro Edition Features: In the PRO edition, console-ninja.allowedHosts supports:

    • Wildcards (e.g., *.example.com)
    • Regular expressions (e.g., /^.*\.example\.com$/)