How to Debug the Insomnia Application Using Its package.json Scripts

Use npm run dev to launch the full development environment, then attach a debugger to the main process on port 5858 or open Chrome DevTools for the renderer process.

Insomnia is a multi-process Electron application built by Kong that follows the classic main process ↔ renderer process model. All entry points, build steps, and debugging configurations are defined in the workspace packages/insomnia/package.json. Understanding these npm scripts allows you to attach debuggers to both the Electron backend and the React frontend without external configuration.

Understanding the Architecture

The Insomnia application runs as two distinct processes. The main process handles Node.js APIs, file system operations, and native integrations, while the renderer process hosts the React-based UI. The package.json in the Insomnia workspace provides orchestrated scripts that launch both processes concurrently with debugging enabled.

Launch the Development Environment

Start the full debugging stack with the root-level command:

npm run dev

This script executes a chain of commands defined across the monorepo. According to the Kong/Insomnia source code, the root package.json (line 28) invokes npm start -w insomnia, which forwards to the packages/insomnia/package.json start script (line 30). This start script uses concurrently to run two subprocesses:

• npm run start:dev-server – Launches the Vite development server for the renderer code on port 3334 (configured in vite.config.ts).
• npm run start:electron – Builds the Electron entry points and starts the Electron binary with the --inspect flag enabled.

Result: You get live-reloading UI components and a main-process instance ready for debugging.

Debug the Main Process

To debug the Electron main process specifically, run:

npm run start:electron

The script ends with electron --inspect=5858 . as defined in packages/insomnia/package.json (line 33). This starts the V8 inspector listening on port 5858, allowing you to attach any Chrome-compatible debugger.

VS Code Configuration

Create a launch.json entry to attach to the main process:

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Insomnia Main",
  "port": 5858,
  "address": "localhost",
  "protocol": "inspector"
}

Once attached, set breakpoints in files under packages/insomnia/src/main/ (such as src/main/ipc/main.ts) to step through startup logic, IPC handlers, and native API calls.

Debug the Renderer Process

The renderer process runs React code served by Vite. Since the dev server already runs on port 3334, you can debug the frontend using standard Chromium tools.

Method 1: Built-in DevTools

With the application running, press Ctrl+Shift+I (or select "Toggle DevTools" from the menu) to open Chrome DevTools attached to the renderer. Here you can set breakpoints in the bundled React source under src/ui/**/*.tsx.

Method 2: Remote Debugging

Launch Electron with an explicit remote debugging port:

npm run start:electron -- --remote-debugging-port=9222

Open chrome://inspect in your browser and select the Insomnia renderer tab to debug the React components with full source maps.

Debug Unit Tests and Type Checking

For debugging single-process Node.js logic without the Electron shell, use the root-level scripts:

npm run type-check   # Runs React Router typegen + tsc

npm run test         # Runs Vitest unit tests

These commands are defined in the root package.json (lines 31-32) and execute respective workspace commands under the hood. You can add --inspect-brk to the Vitest command if you need to step through test logic.

Troubleshooting Common Issues

• No breakpoints hit in main process: Verify that electron --inspect=5858 is running by checking the terminal for Debugger listening on ws://…:5858. Ensure your debugger is attached to port 5858.
• Renderer code appears stale: Confirm the Vite dev server is active (npm run start:dev-server) and that the window is not loading a cached production build. Check vite.config.ts for the dev server configuration.
• Port already in use: Kill stray Node.js or Electron processes with pkill -f electron, or modify the script to use --inspect=0 for a random available port.

Key Files for Debugging

File	Purpose
packages/insomnia/package.json	Defines all dev and debug scripts, including start:electron with the --inspect=5858 flag.
packages/insomnia/src/main/**/*.ts	Entry points for the main process (e.g., src/main/ipc/main.ts).
packages/insomnia/src/ui/**/*.tsx	React UI components running in the renderer process.
vite.config.ts	Configures the Vite dev server (port 3334) and hot-module replacement settings.
electron-builder.config.js	Shows production build packaging; useful for understanding the final binary layout.

Complete Debugging Workflow

Follow this sequence to debug both processes simultaneously:

# 1. Start the dev environment (dev server + electron with inspector)

npm run dev

# 2. In VS Code, launch the "Attach to Insomnia Main" configuration

#    Set breakpoints in src/main/ipc/main.ts

# 3. In the Insomnia window, press Ctrl+Shift+I to open DevTools

#    Set breakpoints in React components like src/ui/components/RequestSidebar.tsx

# 4. Run unit tests with debugging if needed

npm run test

Summary

• npm run dev launches both the Vite dev server and Electron with debugging enabled.
• Main process debugging uses --inspect=5858 defined in packages/insomnia/package.json line 33.
• Renderer debugging uses the Vite dev server on port 3334 and Chrome DevTools (Ctrl+Shift+I).
• Unit tests run via npm run test using Vitest for isolated Node.js debugging.
• Source code for the main process lives in src/main/, while React components reside in src/ui/.

Frequently Asked Questions

How do I change the debugging port for the main process?

Modify the start:electron script in packages/insomnia/package.json (line 33) to change --inspect=5858 to your preferred port, or use --inspect=0 to assign a random available port. You must update your debugger's attach configuration to match the new port.

Can I debug the renderer process in VS Code instead of Chrome DevTools?

Yes, launch Electron with --remote-debugging-port=9222 and configure a VS Code launch task using the Chrome debugger extension. Point it to http://localhost:9222 to attach to the renderer's DevTools protocol, though using the built-in Ctrl+Shift+I DevTools is usually faster for UI debugging.

Why aren't my breakpoints hitting in the main process?

Ensure you are running npm run start:electron (or npm run dev) and see the "Debugger listening on ws://..." message in the terminal. Verify your VS Code or Chrome debugger is attached to port 5858 and that you are opening the source files from packages/insomnia/src/main/ rather than the compiled output.

How do I debug only the TypeScript type checking without running Electron?

Run npm run type-check from the repository root. This executes the React Router type generator and TypeScript compiler without launching the Electron binary, allowing you to isolate type errors in the build pipeline.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}