Navigation

Creating Compass Plugins

Overview

MongoDB Compass plugins allow you to extend Compass and tailor it to meet your specific needs by writing a ReactJS module.

Getting Started

Note

Plugins require MongoDB Compass 1.11 or later.

Install Dependencies

The following are required to begin building MongoDB Compass plugins:

  • MongoDB Compass (version 1.11 or greater)
  • Node Version Manager (NVM)
  • NodeJS
  • Khaos

The following procedure outlines how to install these dependencies:

  1. Install the latest version of MongoDB Compass for your operating system from the MongoDB Download Center.

  2. Install the Node Version Manager (NVM):

    For MacOS and Linux operating systems:

    Follow the installation instructions at https://github.com/creationix/nvm#install-script.

    For Windows operating systems:
    1. Download the nvm-setup.zip file from https://github.com/coreybutler/nvm-windows/releases.
    2. Decompress the downloaded .zip file and run nvm-setup.exe.
  3. Install NodeJS via NVM:

    nvm install stable
    
  4. Install the Khaos templating engine:

    npm install -g khaos
    
  5. Create the MongoDB Compass plugins directory. Compass looks for plugins in this directory:

    MongoDB Compass
    mkdir -p ~/.mongodb/compass/plugins
    
    MongoDB Compass Community Edition
    mkdir -p ~/.mongodb/compass-community/plugins
    

Create an Empty Plugin

Run the following commands to create an empty plugin. Replace <my-plugin> with the name of the plugin you wish to create:

MongoDB Compass
cd ~/.mongodb/compass/plugins
khaos create mongodb-js/compass-plugin ./<my-plugin>
MongoDB Compass Community Edition
cd ~/.mongodb/compass-community/plugins
khaos create mongodb-js/compass-plugin ./<my-plugin>

Enter the following information when prompted:

Field Description
Name

Name of the plugin.

When naming your plugin, Kebab Case is recommended; for example, query-bar. Do not use spaces.

Description A brief description of what your plugin does.
Role

A plugin’s role dictates where it exists within the MongoDB Compass interface. The following roles are available:

For details on these roles, see Plugin Roles.

Run the following commands to navigate to your plugin directory and install the new plugin’s dependencies:

cd ~/.mongo/compass/plugins
cd <plugin-name> && npm install

Run the following command from your plugin’s root directory to build the plugin:

npm run compile

Launch Compass to view your plugin.

Restrictions

Third-party plugins are prohibited from taking any of the following actions:

  1. Accessing network resources over any protocol outside of the database connection. This includes network access via NodeJS or DOM APIs such as XMLHttpRequest.
  2. Accessing the filesystem outside of DOM APIs such as IndexedDB.
  3. Spawning child processes.
  4. Accessing MongoDB Compass internal preferences and core models.

Additional Information

For detailed examples on creating custom MongoDB Compass plugins, see Plugin Tutorials.