Main Commands for Contributing to Insomnia: The Complete npm Script Guide

The root package.json in Kong/insomnia defines npm scripts like npm run dev, npm run lint, npm run test, and npm run app-build that cover the full contribution workflow from development to packaging.

The Insomnia API client is an open-source Electron application maintained by Kong. Understanding the npm scripts defined in the root package.json is essential for anyone contributing to Insomnia, as these commands handle everything from launching the development UI to running smoke tests and packaging the final application.

Development Workflow Commands

Launching the Development Environment

The primary command for local development is npm run dev, which launches the main Insomnia UI in development mode by executing npm start -w insomnia. For iterative development when editing core files, use npm run dev:autoRestart to enable automatic restarts on file changes.

# Start the Electron app in development mode

npm run dev

# Enable auto-restart for rapid iteration

npm run dev:autoRestart

CLI Development

Contributors working on the insomnia-inso CLI tool have dedicated scripts. The npm run inso-start command starts the CLI in watch mode for active development, while npm run inso-package builds and packages the CLI for distribution.

# Start CLI in watch mode

npm run inso-start

# Build and package the CLI

npm run inso-package

Code Quality and Verification

Linting and Type Checking

Before submitting changes, run npm run lint to execute ESLint across all workspaces in the monorepo. This script fails if any linting rules are violated. For type safety verification, npm run type-check runs the TypeScript compiler in "no-emit" mode across all packages without generating output files.

# Check code style across all workspaces

npm run lint

# Verify TypeScript types without emitting files

npm run type-check

Circular Dependency Detection

The repository includes a specialized script to maintain code health. Running npm run check-cycle-references uses madge to detect circular module dependencies across the packages directory, preventing architectural issues before they reach production.

# Detect circular imports in the packages directory

npm run check-cycle-references

Testing Commands

Unit and Integration Tests

The npm run test command executes the complete test suite, including unit and integration tests for every workspace in the monorepo. This is the primary command for verifying that changes do not break existing functionality.

# Run the full test suite across all workspaces

npm run test

Smoke and Critical Test Suites

Insomnia maintains separate test categories for different validation levels. The smoke test suite (located in packages/insomnia-smoke-test/) validates core user flows, while critical tests cover essential functionality.

Run smoke tests against different build stages:

• npm run test:smoke:dev - Test against development build
• npm run test:smoke:build - Test against production bundle
• npm run test:smoke:package - Test against packaged application

Similarly, critical tests use npm run test:crit:dev and npm run test:crit:package to validate essential paths against development and packaged versions.

# Run smoke tests against the built application

npm run test:smoke:build

# Run critical tests against the packaged app

npm run test:crit:package

Build and Packaging

Production Builds

To create a production-ready Electron application, use npm run app-build. This command compiles the main application located in packages/insomnia/ into a distributable format. For development builds of Electron entry points with dev server support, use npm run watch:app.

# Build production-ready Electron app

npm run app-build

# Build Electron entry points with dev server

npm run watch:app

Distribution Packaging

After building, npm run app-package creates the final packaged application for distribution. This script handles platform-specific packaging of the Electron app. For the CLI tool, npm run inso-package performs the equivalent packaging operation for insomnia-inso.

# Package the Electron app for distribution

npm run app-package

# Package the CLI tool

npm run inso-package

Maintenance and Setup

Native Dependencies

Insomnia depends on native node-libcurl binaries that require platform-specific installation. The scripts npm run install-libcurl-electron and npm run install-libcurl-node install the appropriate binaries for Electron and Node.js environments respectively. These run automatically via the postinstall hook after npm install, but can be invoked manually if needed.

# Install libcurl for Electron manually

npm run install-libcurl-electron

Repository Cleanup

When you need a completely fresh start, npm run clean executes git clean -dfX to remove all untracked files from the repository. This is useful when switching between major development branches or troubleshooting build issues.

# Remove all untracked files for a fresh start

npm run clean

Post-Install Hooks

The postinstall script runs automatically after npm install executes. According to the source code in package.json, this hook applies patch packages, verifies bundled plugins, and installs the Electron-specific libcurl binary, ensuring the development environment is ready immediately after dependency installation.

Summary

• The root package.json serves as the central command registry for the Insomnia monorepo, located at https://github.com/Kong/insomnia/blob/develop/package.json.
• Development: Use npm run dev for UI development and npm run inso-start for CLI development.
• Quality: Run npm run lint, npm run type-check, and npm run check-cycle-references before committing changes.
• Testing: Execute npm run test for unit tests, or use test:smoke:build and test:crit:package for integration validation.
• Building: Use npm run app-build to compile the Electron app and npm run app-package to create distributables.
• Maintenance: The postinstall hook handles native dependencies automatically, while npm run clean resets the repository state.

Frequently Asked Questions

What is the difference between npm run dev and npm run watch:app?

npm run dev launches the main Insomnia UI by running npm start -w insomnia, providing the full development environment with the renderer process. In contrast, npm run watch:app specifically builds Electron entry points and starts the dev server for the main process, which is useful when working on main-thread code rather than the UI components.

How do I run tests for a specific part of the Insomnia application?

While npm run test runs the full suite across all workspaces, the smoke and critical test scripts target specific validation levels. Use npm run test:smoke:dev to test against a development build, npm run test:smoke:build for production bundles, or npm run test:crit:package for critical path validation on packaged apps. Unit tests for specific packages can typically be run using npm workspace filters.

What should I do if the libcurl native module fails to install?

If the automatic installation fails during npm install, manually trigger the installation using npm run install-libcurl-electron for the Electron environment or npm run install-libcurl-node for Node.js. These scripts ensure the correct native binary is downloaded and configured for your platform, which is essential for Insomnia's HTTP request functionality.

When should I use npm run check-cycle-references?

Run npm run check-cycle-references whenever you refactor module imports or create new inter-package dependencies. This command uses madge to scan the packages directory for circular dependencies, which can cause runtime errors and bundling issues in Electron applications. Incorporating this check into your pre-commit workflow helps maintain the architectural integrity of the monorepo.

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