# Understanding the Role of Scripts in Insomnia's package.json for Build and Test Pipelines

> Discover how scripts in Insomnia's package.json streamline build and test pipelines, orchestrating everything from code generation and bundling to testing and packaging for efficient development.

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

---

**The `scripts` section in [`packages/insomnia/package.json`](https://github.com/Kong/insomnia/blob/main/packages/insomnia/package.json) serves as the central command center for the Kong/insomnia Electron application, orchestrating everything from React Router type generation and esbuild bundling to Vitest unit testing and electron-builder packaging.**

Kong/insomnia is a monorepo-style Electron application where the `scripts` field in [`packages/insomnia/package.json`](https://github.com/Kong/insomnia/blob/main/packages/insomnia/package.json) defines the entire build and test lifecycle. These npm commands chain together tools like esbuild, Vite, and electron-builder to transform TypeScript source code into shippable binaries while enforcing code quality through automated linting and unit testing.

## Core Build Scripts

The production build process relies on interconnected scripts that generate static assets, compile entry points, and verify bundled plugins.

### Production Build Pipeline

The **`build`** script executes the full production pipeline defined in [`packages/insomnia/scripts/build.ts`](https://github.com/Kong/insomnia/blob/main/packages/insomnia/scripts/build.ts). This script generates React Router routes, compiles entry points using **esbuild**, copies static assets, and outputs to a `build/` directory containing [`entry.main.min.js`](https://github.com/Kong/insomnia/blob/main/entry.main.min.js) and [`entry.preload.min.js`](https://github.com/Kong/insomnia/blob/main/entry.preload.min.js). It also triggers `verify-bundle-plugins` to validate that third-party plugins conform to the expected schema before release.

### React Router Type Generation

The **`build:react-router`** script invokes the React Router CLI to generate route-loader and action files from the `src/routes/` directory. This step creates the type-safe routing layer required for the application to lazily load pages, and it runs automatically as part of the main build process.

### Electron Entry Point Compilation

During development, the **`build:electron-entrypoints`** script uses [`esbuild.entrypoints.ts`](https://github.com/Kong/insomnia/blob/main/esbuild.entrypoints.ts) to compile the `main` and `preload` Electron entry points under `NODE_ENV=development`. This enables hot-reloading when paired with `start:electron` commands.

## Development and Quality Assurance

Maintaining code quality and type safety requires dedicated scripts that run in CI to block defective code from reaching production.

### Linting and Type Checking

The **`lint`** script runs ESLint across all `.js`, `.ts`, and `.tsx` files using the root `.eslintrc.*` configuration to enforce style consistency. The **`type-check`** script first runs `react-router typegen` to generate route typings, then executes the TypeScript compiler (`tsc`) against the monorepo's [`tsconfig.json`](https://github.com/Kong/insomnia/blob/main/tsconfig.json) to verify type consistency across the codebase.

### Unit Testing with Vitest

The **`test`** command executes the unit test suite using **Vitest** (`vitest run`), targeting test files co-located with source code (`*.test.ts`). This script runs on every pull request via GitHub Actions to verify functional correctness before merging.

## Packaging and Distribution

Creating installable binaries requires scripts that handle native dependencies and invoke electron-builder.

### Binary Packaging

The **`package`** script first runs `npm run build` to ensure the `build/` directory exists, then hands the `dist/` folder to **electron-builder** (configured via [`electron-builder.config.js`](https://github.com/Kong/insomnia/blob/main/electron-builder.config.js)) to produce installers for macOS, Windows, and Linux. Platform-specific variants like **`package:windows:unpacked`** generate raw unpacked builds for fast local testing alongside full installers for end-users.

### Native Dependency Management

The **`install-x64-native-dependencies`** script executes [`scripts/install-x64-native-dependencies.ts`](https://github.com/Kong/insomnia/blob/main/scripts/install-x64-native-dependencies.ts) to compile native Node modules (such as `@getinsomnia/node-libcurl`) for x64 architecture. This step runs on CI agents before building the Electron binary to ensure proper bindings exist.

## Asset and Plugin Verification

Specialized scripts handle static assets and plugin validation outside the standard build flow.

The **`convert-svg`** script uses **@svgr/cli** (configured via [`svgr.config.js`](https://github.com/Kong/insomnia/blob/main/svgr.config.js)) to transform SVG files from `src/ui/components/assets/svgr` into React components. The **`verify-bundle-plugins`** script runs [`scripts/verify-bundle-plugins.ts`](https://github.com/Kong/insomnia/blob/main/scripts/verify-bundle-plugins.ts) as a pre-publish safety net to check that bundled plugins are correctly bundled and schema-compliant, aborting the CI workflow on failure.

## CI/CD Pipeline Execution Flow

The scripts compose into a deterministic pipeline that CI executes in sequence.

1. **Validation Phase**: `npm run lint && npm run type-check` ensures code quality and type safety before any heavy compilation.
2. **Build Phase**: `npm run build` creates the production bundle and runs verification scripts.
3. **Test Phase**: `npm run test` executes Vitest in parallel to the build to verify functionality.
4. **Packaging Phase**: `npm run package` feeds the `build/` output into electron-builder to generate signed binaries.

Optional steps like `convert-svg` and `install-x64-native-dependencies` run on demand or during full release jobs to keep assets and native dependencies synchronized.

## Practical Command Reference

Use these commands to interact with the Insomnia codebase locally or in automation:

```bash

# Start the full development environment (Vite + Electron with hot-reload)

npm start

# Run the production build (generates build/ directory with minified entry points)

npm run build

# Execute the unit test suite with Vitest

npm test

# Generate installable binaries for all platforms

npm run package

# Create a Windows unpacked build for rapid local testing

npm run package:windows:unpacked

# Install x64 native dependencies required for Electron builds

npm run install-x64-native-dependencies

```

## Summary

- The **`scripts`** section in [`packages/insomnia/package.json`](https://github.com/Kong/insomnia/blob/main/packages/insomnia/package.json) acts as the single source of truth for the build and test pipeline in Kong/insomnia.
- **Build scripts** (`build`, `build:react-router`, `build:electron-entrypoints`) handle esbundling, route generation, and asset compilation.
- **Quality scripts** (`lint`, `type-check`, `test`) enforce ESLint rules, TypeScript correctness, and unit test coverage via Vitest.
- **Packaging scripts** (`package`, `install-x64-native-dependencies`) prepare native bindings and invoke electron-builder to create cross-platform installers.
- **Verification scripts** (`verify-bundle-plugins`, `convert-svg`) ensure plugin integrity and convert SVG assets to React components before release.

## Frequently Asked Questions

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

`npm run build` compiles the application source code using esbuild and generates the `build/` directory containing [`entry.main.min.js`](https://github.com/Kong/insomnia/blob/main/entry.main.min.js) and static assets. `npm run package` invokes electron-builder to take those built assets and create installable binaries (`.dmg`, `.exe`, `.AppImage`) for distribution.

### How does Insomnia handle type generation for React Router routes?

The `build:react-router` script runs the React Router CLI to generate type-safe route loaders and action files from the `src/routes/` directory. This occurs automatically during the main build process and is essential for the application's lazy loading architecture.

### Why does the CI pipeline run `install-x64-native-dependencies` before building?

Electron applications rely on native Node modules like `@getinsomnia/node-libcurl` that must be compiled for the target architecture. The `install-x64-native-dependencies` script ensures these bindings are correctly installed on x64 CI agents before the `package` script attempts to bundle the Electron binary.

### What testing framework does Insomnia use, and how is it triggered?

Insomnia uses **Vitest** for unit testing, triggered by the `test` script which runs `vitest run` against test files co-located with source code (`*.test.ts`). This executes in CI on every pull request to prevent regressions.