# Main Commands for Contributing to Insomnia: The Complete npm Script Guide > Master Insomnia contributions with key npm scripts like npm run dev, npm run lint, and npm run test. Explore the complete contribution workflow from development to packaging directly from package.json. - Repository: [Kong/insomnia](https://github.com/Kong/insomnia) - Tags: how-to-guide - Published: 2026-06-27 --- **The root [`package.json`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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. ```bash # 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. ```bash # 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. ```bash # 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. ```bash # 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. ```bash # 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. ```bash # 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`. ```bash # 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`. ```bash # 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. ```bash # 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. ```bash # 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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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.