# How Insomnia Manages Its Dependencies: Inside the Kong/insomnia package.json Architecture

> Explore how Insomnia manages dependencies via its npm-workspace monorepo architecture. The root package.json orchestrates tooling while individual packages manage runtime needs for robust builds and plugins.

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

---

**Insomnia organizes its codebase as an npm-workspace monorepo where the root [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json) orchestrates shared tooling and workspace definitions, while individual packages like `packages/insomnia` maintain specific runtime dependencies, enabling deterministic builds and modular plugin support.**

The Kong/insomnia repository relies on a sophisticated dependency management strategy that balances centralized control with package-level flexibility. By examining the [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json) files throughout the repository, you can see how the project handles everything from Node version enforcement to optional plugin dependencies. This architecture ensures that the Electron-based API client remains maintainable while supporting extensible features.

## Root package.json: The Workspace Orchestrator

The root [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json) serves as the central command center for the entire monorepo, defining the workspace boundaries and shared infrastructure that all packages inherit.

### Workspace Configuration and Dependency Hoisting

The `workspaces` array in the root configuration enumerates all sub-packages that belong to the monorepo. When `npm install` runs at the repository root, npm resolves the dependency graph across all workspaces, **hoisting shared dependencies** to the root `node_modules` while keeping workspace-specific packages isolated.

```json
"workspaces": [
  "packages/insomnia-testing",
  "packages/insomnia",
  "packages/insomnia-data",
  ...
]

```

This structure allows code sharing between packages (such as the data layer in `packages/insomnia-data`) without duplicating tooling installations across the entire repository.

### Engine Requirements and Node Version Management

Insomnia requires **Node.js ≥ 24** and **npm ≥ 11**, as declared in the `engines` field of the root [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json). The `.nvmrc` file pins the exact Node version (24.14.0) used by CI and development environments, ensuring consistency across contributor machines.

```json
"engines": {
  "node": ">=24.0.0",
  "npm": ">=11.0.0"
}

```

### Shared Development Tooling

Rather than declaring linting, testing, and build tools in every workspace, the root [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json) centralizes these **devDependencies**. This prevents version drift and speeds up installation times.

```json
"devDependencies": {
  "@eslint/js": "^9.23.0",
  "typescript": "5.8.3",
  "vitest": "^3.2.4",
  ...
}

```

High-level scripts in the root file proxy commands to specific workspaces using the `-w` flag (for example, `npm run lint -w insomnia`). The `postinstall` hook runs `patch-package` and installs the native `libcurl` binary for Electron via `install-libcurl-electron`.

### Dependency Overrides for Reproducibility

The `overrides` section in the root configuration forces specific sub-dependency versions across the entire monorepo. For instance, particular `ajv` versions are pinned for `ajv-draft-04` compatibility, guaranteeing reproducible builds regardless of transient dependency updates.

## Workspace-Level Dependencies in packages/insomnia

While the root manages the orchestration, [`packages/insomnia/package.json`](https://github.com/Kong/insomnia/blob/main/packages/insomnia/package.json) contains the specific runtime dependencies required by the main Electron application.

### Core Runtime Dependencies

The main application layer pulls in React 18, React Router 7, TailwindCSS, and Electron-specific helpers like `electron-updater` and `electron-context-menu`. The networking stack includes libraries such as `@grpc/grpc-js`, `undici`, `node-forge`, and `@apideck/better-ajv-errors` to handle request execution, GraphQL support, and cryptographic operations.

### Optional Dependencies for Plugin Extensibility

Insomnia declares optional plugins as `optionalDependencies`, allowing the core application to remain lightweight while supporting third-party extensions that load only when needed.

```json
"optionalDependencies": {
  "@kong/insomnia-plugin-ai": "^1.0.11",
  "@kong/insomnia-plugin-external-vault": "0.1.4-dev.20251224090833"
}

```

These packages resolve to no-op implementations if not installed, preventing runtime errors while maintaining extensibility.

### Build and Verification Scripts

Workspace-specific scripts in [`packages/insomnia/package.json`](https://github.com/Kong/insomnia/blob/main/packages/insomnia/package.json) handle building Electron entry points, packaging the application, and running unit tests with Vitest. The `verify-bundle-plugins` script checks that bundled plugins meet the expected ABI before packaging, ensuring compatibility with the current Electron runtime.

## Installation and Development Workflow

To install the entire monorepo with the correct Node version:

```bash

# Switch to the Node version declared in .nvmrc

fnm use "$(cat .nvmrc)"   # or `nvm use` if you have nvm installed

# Install all dependencies with exact, reproducible resolution

npm ci

```

To add a new runtime dependency specifically to the UI package:

```bash

# From the repo root, add the dependency only to the UI workspace

npm install lodash@4.17.21 -w packages/insomnia

```

The `-w` flag updates [`packages/insomnia/package.json`](https://github.com/Kong/insomnia/blob/main/packages/insomnia/package.json) and places the package in that workspace's `node_modules` hierarchy (or hoists it if shared with other workspaces).

When loading optional plugins at runtime, the application uses a pattern that handles missing dependencies gracefully:

```typescript
import { loadPlugin } from 'insomnia-plugin-manager';

async function init() {
  // Resolves to the optional dependency if installed, otherwise null
  const aiPlugin = await loadPlugin('@kong/insomnia-plugin-ai');
  aiPlugin?.initialize();
}

```

## Summary

- **Insomnia uses npm workspaces** to manage a monorepo structure, with the root [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json) defining shared devDependencies and workspace boundaries.
- **Node.js ≥ 24 and npm ≥ 11** are strictly enforced through the `engines` field and `.nvmrc` file to ensure build consistency.
- **Native dependencies** like `libcurl` are managed through `postinstall` hooks that match binaries to the Electron runtime.
- **Optional dependencies** allow plugins to remain external while providing runtime extensibility without breaking the core application.
- **Dependency overrides** in the root configuration guarantee reproducible builds by pinning specific sub-dependency versions across all workspaces.

## Frequently Asked Questions

### What Node version does Insomnia require?

Insomnia requires **Node.js 24 or higher** and **npm 11 or higher**, as specified in the `engines` field of the root [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json). The `.nvmrc` file pins the exact version (24.14.0) to ensure CI and local development environments remain synchronized.

### How does Insomnia handle plugin dependencies?

Plugins are declared as `optionalDependencies` in [`packages/insomnia/package.json`](https://github.com/Kong/insomnia/blob/main/packages/insomnia/package.json), which means they install automatically when available but do not break the build if missing. The [`verify-bundle-plugins.ts`](https://github.com/Kong/insomnia/blob/main/verify-bundle-plugins.ts) script validates that bundled plugins match the expected ABI before packaging, ensuring runtime compatibility with the Electron binary.

### Why does Insomnia use npm workspaces instead of a single package.json?

The npm workspace structure allows Insomnia to **share code** between packages (like the data layer in `packages/insomnia-data`) while maintaining **isolated dependency trees** for specific components. This prevents version conflicts between the Electron app's runtime dependencies and the development tooling, while enabling modular architecture for testing utilities and core libraries.

### How are native dependencies like libcurl managed?

Native dependencies are installed through the `postinstall` hook in the root [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json), which executes `install-libcurl-electron`. This ensures the native binary matches the specific Electron runtime headers, preventing ABI mismatches that could crash the application when making HTTP requests.