# How to Build the Insomnia Project from Source Using package.json Scripts > Build the Insomnia project from source using npm scripts. Follow this guide to compile TypeScript, bundle with Vite, and prepare the Electron app for distribution. - Repository: [Kong/insomnia](https://github.com/Kong/insomnia) - Tags: how-to-guide - Published: 2026-06-27 --- **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`](https://github.com/Kong/insomnia/blob/main/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: ```bash # 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: ```bash 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: ```bash 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`](https://github.com/Kong/insomnia/blob/main/package.json) orchestrates these steps, ensuring the TypeScript sources in [`packages/insomnia/src/main/preload.ts`](https://github.com/Kong/insomnia/blob/main/packages/insomnia/src/main/preload.ts) and the Vite configuration at [`packages/insomnia/src/renderer/vite.config.ts`](https://github.com/Kong/insomnia/blob/main/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: ```bash 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`: ```bash 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`](https://github.com/Kong/insomnia/blob/main/package.json)** (root) – Defines the top-level `build`, `dev`, and `package` scripts alongside the workspace configuration that maps to `packages/*`. - **[`packages/insomnia/package.json`](https://github.com/Kong/insomnia/blob/main/packages/insomnia/package.json)** – Contains the Electron-specific build configuration and scripts that invoke `electron-builder`. - **[`packages/insomnia/src/main/preload.ts`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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.