How to Build the Insomnia Project from Source Using package.json Scripts

To build Insomnia from source, run npm ci followed by npm run build in the repository root, which uses npm workspaces to compile TypeScript, bundle the renderer with Vite, and prepare the Electron application for distribution.

The Kong/insomnia repository is organized as an npm monorepo where build orchestration happens through standardized scripts defined in the root package.json. Learning how to build the Insomnia project from source using package.json scripts enables you to compile the TypeScript codebase, bundle the React-based renderer, and package the Electron app without manually configuring complex toolchains.

Prerequisites

Before executing any scripts, ensure your environment matches the repository requirements. The project includes a .nvmrc file that pins the required Node.js version (currently v20.x). Install and activate this version using a Node version manager:

# Using fnm

fnm use "$(cat .nvmrc)"

# Or using nvm

nvm use

Verify the installation with node -v before proceeding to dependency installation.

Install Dependencies

Because the repository uses npm workspaces, you must install dependencies from the root directory to populate node_modules for all packages simultaneously:

npm ci

This command performs a clean install respecting the lockfile and establishes symlinks for the workspace packages located in packages/insomnia, packages/insomnia-data, and packages/insomnia-api.

Build the Application

The primary compilation step is triggered by the root-level build script. According to the Kong/insomnia source code, this script delegates to individual workspace builds using the -w flag:

npm run build

Internally, this executes the following workspace commands in dependency order:

• npm run -w packages/insomnia build – Compiles the main Electron process and bundles the renderer using Vite.
• npm run -w packages/insomnia-data build – Transpiles the NeDB-based data layer that manages local storage.
• npm run -w packages/insomnia-api build – Bundles the cloud API client used for synchronization features.

The build script defined in the root package.json orchestrates these steps, ensuring the TypeScript sources in packages/insomnia/src/main/preload.ts and the Vite configuration at packages/insomnia/src/renderer/vite.config.ts are processed correctly.

Development Workflow

For rapid iteration without producing production bundles, use the dev script. This launches the Vite development server for the renderer and starts the Electron process with hot-reload enabled:

npm run dev

This mode watches source files across all workspaces and automatically reloads the UI when changes are detected in the TypeScript or React components.

Create Distributable Packages

After running npm run build, you can generate platform-specific installers and binaries using the package script, which wraps electron-builder:

npm run package

The resulting distributables appear in packages/insomnia/dist/ and include .exe, .dmg, or .AppImage files depending on your operating system.

Key Configuration Files

Understanding the build process requires familiarity with these specific files in the Kong/insomnia repository:

• package.json (root) – Defines the top-level build, dev, and package scripts alongside the workspace configuration that maps to packages/*.
• packages/insomnia/package.json – Contains the Electron-specific build configuration and scripts that invoke electron-builder.
• packages/insomnia/src/main/preload.ts – The entry point for the Electron preload script, compiled during the build process to establish secure context bridging.
• packages/insomnia/src/renderer/vite.config.ts – The Vite configuration file that controls bundling for the React-based user interface, referenced by the build and dev scripts.
• packages/insomnia-data/package.json – Defines the build script for the data persistence layer that compiles NeDB models and utilities.
• packages/insomnia-api/package.json – Specifies the build configuration for the cloud synchronization API client.

Summary

• Environment: Use Node.js v20.x as specified in .nvmrc before installing dependencies.
• Installation: Run npm ci from the repository root to install all workspace dependencies.
• Compilation: Execute npm run build to trigger workspace-specific builds via the -w flag, compiling TypeScript and bundling the renderer with Vite.
• Development: Use npm run dev for hot-reload development mode across the monorepo.
• Distribution: Run npm run package after building to generate installable binaries via electron-builder.

Frequently Asked Questions

What Node.js version is required to build Insomnia?

You must use the exact version specified in the .nvmrc file (currently Node.js v20.x). The build scripts rely on modern npm workspace features and Vite plugins that require this specific version to function correctly.

How do I build only a specific workspace package?

You can target a specific workspace using the -w flag followed by the package path. For example, to build only the data layer, run npm run -w packages/insomnia-data build. This is useful when making isolated changes to a single package.

What is the difference between npm run build and npm run package?

The build script compiles TypeScript sources and bundles the application resources, producing development or production-ready code in the dist directories. The package script runs after build and uses electron-builder to wrap those compiled assets into platform-specific installers (such as .exe or .dmg files).

Where are the compiled binaries located after running the package script?

According to the repository structure, the packaged binaries and installers are written to packages/insomnia/dist/. This directory contains subfolders for different platforms and formats, including portable executables and installer packages.

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