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

Insomnia organizes its codebase as an npm-workspace monorepo where the root 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 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 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.

"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. The .nvmrc file pins the exact Node version (24.14.0) used by CI and development environments, ensuring consistency across contributor machines.

"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 centralizes these devDependencies. This prevents version drift and speeds up installation times.

"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 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.

"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 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:

# 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:

# 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 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:

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 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. 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, which means they install automatically when available but do not break the build if missing. The 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, 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.

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