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

> Debug the Insomnia app effectively by leveraging its package.json scripts. Launch the dev environment with npm run dev and attach a debugger or use Chrome DevTools for seamless troubleshooting.

- Repository: [Kong/insomnia](https://github.com/Kong/insomnia)
- Tags: how-to-guide
- Published: 2026-06-27

---

**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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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:

```bash
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`](https://github.com/Kong/insomnia/blob/main/package.json) (line 28) invokes `npm start -w insomnia`, which forwards to the **[`packages/insomnia/package.json`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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:

```bash
npm run start:electron

```

The script ends with `electron --inspect=5858 .` as defined in [`packages/insomnia/package.json`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/launch.json) entry to attach to the main process:

```json
{
  "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`](https://github.com/Kong/insomnia/blob/main/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:

```bash
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:

```bash
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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/src/main/ipc/main.ts)). |
| **`packages/insomnia/src/ui/**/*.tsx`** | React UI components running in the renderer process. |
| **[`vite.config.ts`](https://github.com/Kong/insomnia/blob/main/vite.config.ts)** | Configures the Vite dev server (port 3334) and hot-module replacement settings. |
| **[`electron-builder.config.js`](https://github.com/Kong/insomnia/blob/main/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:

```bash

# 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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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.