Introduction to Plugins
This section provides an overview of Insomnia’s plugins, which can be used to extend the functionality of Insomnia. Plugins are commonly used when more advanced behavior is needed, like custom authentication mechanisms and complex workflows.
You can create your own Insomnia plugin and upload it via Insomnia Preferences within the app or via NPM. Generally, plugins do the following:
- Add a custom template tag for rendering custom values
- Define a hook that can do things like intercept requests and responses to add custom behavior
Browse our current community NPM plugins on the Insomnia Plugin Hub.
Create a Plugin
An Insomnia plugin is a NodeJS module that is placed in a specific directory that Insomnia will recognize.
Plugin File Location
In order for Insomnia to recognize your plugin as an Insomnia plugin, your files must live in the following locations:
$XDG_CONFIG_HOME/Insomnia/plugins/ or ~/.config/Insomnia/plugins/
Note: To quickly create a plugin in the proper path with starter files via the Insomnia app, go to Preferences and click on the Plugins tab. Click on Generate New Plugin and enter your plugin name. If you don’t prepend the title with insomnia-plugin-, it will automatically be added.
Plugin File Structure
An Insomnia plugin directory requires at least two files. In the following example, the plugin title is
base64 and contains the files
├── package.json # Node module metadata
package.json configuration includes the following content:
- name (must be prepended with
- main (file entry point)
- Insomnia-specific metadata
- Optional plugin metadata
- External dependencies
The following is an example minimal
package.json must contain an
insomnia attribute to be identified as an Insomnia plugin.
"name": "insomnia-plugin-base64", // NPM module name, must be prepended with insomnia-plugin-
"version": "1.0.0", // Plugin version
"main": "app.js", // Entry point
// Insomnia-specific metadata. Without this, Insomnia won't recognize the module as a plugin.
"name": "base64", // Internal Insomnia plugin name
"displayName": "base64 Plugin", // Plugin display name
"description": "The base64 plugin encodes and decodes basic strings.", // Plugin description
// Optional plugin metadata
// Plugin images for Plugin Hub and other interfaces
// Plugin Icon
// Suggested filetype: SVG (for scaling)
// Suggested dimensions: 48x48
"icon": "icon.svg", // relative path, relative to package root
// Plugin Cover Image
// Suggested filetype: SVG (for scaling)
// Suggested dimensions: 952w x 398h
"cover": "cover.svg", // relative path, relative to package root
// Force plugin hub and other entities to show specific author details
// Useful for teams and organizations who work on the same plugin
"name": "YOUR NAME HERE", // Plugin publisher name, displayed on plugin hub
"icon": "https://...", // Plugin publisher avatar or icon, absolute url
// External dependencies are also supported
The Plugins tab in the Preferences menu enables the following functionality:
- Add an existing plugin
- Create a new plugin locally
- Toggle a plugin to enable or disable it
- Reveal the exact local plugin location on your machine
Note: Plugins can be downloaded and installed directly from the Insomnia Plugin Hub.
Before you publish your plugin, ensure you have met the following criteria for your plugin to be recognized by Insomnia and be available on the Insomnia Plugin Hub.
Your plugin should:
- Include a correctly structured
package.json file containing the
insomnia attribute. See Plugin package.json for more info.
- Have a package name prefixed with
- Be publicly available.
After you have verified that your plugin meets the criteria described above, publish your public plugin following the NPM publish unscoped public packages instructions. Publish an unscoped package to ensure it appears on the Insomnia Plugin Hub.
If your package does not show up on the Insomnia Plugin Hub after a few days, please contact us with the name of your plugin and a link to the published NPM package.
Publish Scoped Plugins
Insomnia can also use private (scoped) plugins. This commonly enables enterprise users to keep the plugin private from Insomnia.
To enable private (scoped) plugins:
- Navigate to the
plugins directory in Application Data.
npm install @scoped/plugin.
Debug in the Insomnia App
The Insomnia app enables debugging with Chrome DevTools. To open DevTools, click View then Toggle DevTools.
If you want to focus specifically on the plugin you are developing, you can find it from the Sources tab and/or filter the Console based on the plugin’s file name.
Refer to Template Tags for more information.