Skip to content
The GUI for MongoDB.
JavaScript CSS HTML Shell
Branch: master
Clone or download

Latest commit

Anemy Add compass shell plugin (#1963)
* Add compass shell plugin, bump compass home version

* Bump compass-aggregations

* Bump mongosh version to 0.0.2-alpha.0
Latest commit 6699cdf Jun 3, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
.evergreen COMPASS-3933: Update to Electron 6.0.11 (#1873) Jan 29, 2020
.github remove colons at the end of title yaml in github issue templates (#1878) Jan 6, 2020
src Add overflow auto to global styled tab nav bar May 14, 2020
test COMPASS-3710: Migrating all connections to new disk model Aug 28, 2019
.babelrc Compass using React components May 21, 2016
.eslintignore INT-1098: Use hadron-build (#346) Apr 18, 2016
.eslintrc Fix eslint settings and errors (#1702) Apr 26, 2019
.evergreen.yml Run on 10.14 codesign box May 27, 2020
.gitignore factor out instnce plugin to be a standalone Feb 7, 2018
.npmrc COMPASS-3113: Rewrite evergreen integration (#1569) Nov 19, 2018
.snyk fix: .snyk & package.json to reduce vulnerabilities Aug 14, 2018
.travis.yml remove NPM_TOKEN from travis.yml (#1930) Mar 30, 2020 COMPASS-3823: Add CLA requirement to Sep 18, 2019
LICENSE COMPASS-3823 Switched to SSPL Aug 28, 2019 update node and npm requirements in README (#1945) Apr 28, 2020 fix apache 2 default copyright Sep 18, 2019
compass-screenshot.png README updates: screenshot, development, plugin info Sep 26, 2019
package-lock.json Add compass shell plugin (#1963) Jun 3, 2020
package.json Add compass shell plugin (#1963) Jun 3, 2020

MongoDB Compass

The MongoDB GUI.

Aggregation Pipeline Builder Tab in Compass


Running Compass locally requires Node.js and npm:

  • Node.js: ^12.4.0
  • npm: >= >=6.13.0
npm install
npm start [compass|compass-readonly|compass-isolated]


Current Plugin API Version: 3.0.0

Majority of Compass' functionality lives in various plugins outside the main repo. This repo just brings them all together. All external plugins are tagged via the compass-plugin topic in the mongodb-js organisation. There are also various compass-tools and compass-ui-tools packages that help put together the application.

Plugins can be added to Compass by requiring them as a dependency in package.json, and by adding their installed location to the distribution plugin list also in the package.json. Plugin's apiVersion field has to match Compass'. Currently it's at 3.0.0.

Example of adding a dependancy:

npm i -S @mongodb-js/compass-aggregations@latest

And in package.json:

"distributions": {
  "plugin-prefix": "@mongodb-js/compass",
  "default": "compass",
  "compass": {
    "name": "mongodb-compass",
    "plugins": [
      "node_modules/@mongodb-js/compass-aggregations", // add compass-aggregations
      // rest of the plugins required for this distribution
    "styles": [
  // other distribution config

Plugin Roles

Compass determines functionality of a plugin based on its registered Role. There are a few mains ones that we use:

  • Instance.Tab - Display as tabs in the instance context of the app. For example, server-status-plugin.
  • Database.Tab - Display as tabs in the database context of the app. compass-collections-ddl is registered as a Database.Tab, for example.
  • Collection.Tab - Display as sub tabs in the collection context of the app. A good example of this is the compass-crud.
  • Global.Modal - Will open as modal dialogs in any context of the app. These can be separate plugins entirely, or part of an existing plguin that does something else. For example, compass-aggregations is an Collection.Tab, but also registers a Global.Modal.
  • Collection.ScopedModal - Will open as a modal scoped in the collection context. compass-import-export, for example, registers 2 ScopedModals - one for import and the other for export.

Creating a New Plugin

We use a template to create new plugins. It comes set up with packages we might need to be using, and an electron environment to debug and test the plugin. The template is managed by khaos

npm i -g khaos
khaos create mongodb-js/compass-plugin ./my-plugin


For issues, please create a ticket in our JIRA Project.

For contributing, please refer to

Is there anything else you’d like to see in Compass? Let us know by submitting suggestions in out feedback forum.



You can’t perform that action at this time.