This repository contains MongoDB Compass application source, all Compass plugins and most of application dependencies and build tooling for the app.

• mongodb-compass: MongoDB Compass Application

• @mongodb-js/compass-aggregations: Compass Aggregation Pipeline Builder
• @mongodb-js/compass-app-stores: The external stores repo for compass
• @mongodb-js/compass-auto-updates: Compass Auto Updates Plugin
• @mongodb-js/compass-collection: Compass Collection Plugin
• @mongodb-js/compass-collection-stats: Compass Collection Stats Plugin
• @mongodb-js/compass-connect: Connection Screen Plugin that supports Compass
• @mongodb-js/compass-crud: Compass Plugin for CRUD Operations
• @mongodb-js/compass-database: Compass Database Plugin
• @mongodb-js/compass-databases-collections: Plugin for viewing the list of, creating, and dropping databases and collections
• @mongodb-js/compass-deployment-awareness: Compass Deployment Awareness Plugin
• @mongodb-js/compass-explain-plan: Evaluate the performance of your quer
• @mongodb-js/compass-export-to-language: export to language modal
• @mongodb-js/compass-field-store: FieldStore keeps track of available fields in a collection.
• @mongodb-js/compass-find-in-page: cmd-f UI for compass
• @mongodb-js/compass-home: Home
• @mongodb-js/compass-import-export: Compass Import/Export Plugin
• @mongodb-js/compass-indexes: Indexes support for Compass
• @mongodb-js/compass-instance: compass instance plugin
• @mongodb-js/compass-loading: Compass Loading Screen
• @mongodb-js/compass-metrics: Compass Metrics Plugin
• @mongodb-js/compass-plugin-info: Compass Plugin Information Plugin
• @mongodb-js/compass-query-bar: Renders a component for executing MongoDB queries through a GUI.
• @mongodb-js/compass-query-history: The query history sidebar.
• @mongodb-js/compass-schema: Compass Schema Tab Plugin
• @mongodb-js/compass-schema-validation: Compass plugin for document JSON schema validation
• @mongodb-js/compass-server-version: Compass Server Version
• @mongodb-js/compass-serverstats: Compass Real Time Server Stats Component.
• @mongodb-js/compass-shell: Compass Shell Plugin
• @mongodb-js/compass-sidebar: Sidebar external plugin
• @mongodb-js/compass-ssh-tunnel-status: Compass SSH Tunnel Status
• @mongodb-js/compass-status: Compass Status Plugin

• @mongodb-js/hadron-plugin-manager: Hadron Plugin Manager
• @mongodb-js/mongodb-notary-service-client: A client for our notary-service: an API for codesigning.
• @mongodb-js/mongodb-redux-common: Common Redux Modules for mongodb-js
• app-migrations: Helper for application schema migrations.
• compass-preferences-model: Compass preferences model.
• compass-user-model: MongoDB user model.
• electron-license: Tools for electron apps to work with licenses
• hadron-app: Hadron Application Singleton
• hadron-app-registry: Hadron App Registry
• hadron-auto-update-manager: Atoms AutoUpdateManager class as a standalone module.
• hadron-build: Tooling for Hadron apps.
• hadron-compile-cache: Hadron Compile Cache
• hadron-document: Hadron Document
• hadron-ipc: Simplified IPC for electron apps.
• hadron-module-cache: Hadron Module Cache
• hadron-react-bson: Hadron React BSON Components
• hadron-react-buttons: Hadron React Button Components
• hadron-react-components: Hadron React Components
• hadron-react-utils: Hadron React Utils
• hadron-reflux-store: Hadron Reflux Stores
• hadron-style-manager: Hadron Style Manager
• hadron-type-checker: Hadron Type Checker
• mongodb-ace-mode: MongoDB Mode for the ACE Editor
• mongodb-ace-theme: MongoDB Theme for the ACE Editor
• mongodb-ace-theme-query: MongoDB Theme for the ACE Editor in the Query Bar
• mongodb-collection-model: MongoDB collection model.
• mongodb-connection-model: MongoDB connection model.
• mongodb-data-service: MongoDB Data Service
• mongodb-database-model: MongoDB database model.
• mongodb-explain-compat: Convert mongodb SBE explain output to 4.4 explain output
• mongodb-explain-plan-model: Ampersand model abstraction for MongoDB explain plans (3.0+)
• mongodb-index-model: MongoDB index model.
• mongodb-instance-model: MongoDB instance model.
• mongodb-js-metrics: Shareable metric recording.
• mongodb-language-model: Parses MongoDB query language and returns an abstract syntax tree
• mongodb-security: Portable business logic of MongoDB security model
• storage-mixin: Ampersand model mixin to persist data via various storage backends

You'll need node ^12.4.0 and npm 7 installed on your machine to work with the repository locally. After your environment is ready, navigate to the repository and run npm run bootstrap, this will install dependencies and will compile all packages.

After bootstrap is finished, you should be able to run npm run start and see Compass application running locally.

This monorepo is powered by npm workspaces an lerna, although not necessary, it might be helpful to have a high level understanding of those tools.

Most of the plugins have their own development environment so you can work on them in isolation. If you want to work on plugin without running the whole Compass application, you can run npm run start in the plugin directory, either with the help of lerna or npm workspaces. For example to start compass-connect plugin locally you can run npm run start --workspace @mongodb-js/compass-connect or npx lerna run start --scope @mongodb-js/compass-connect --stream.

If you want to see your changes applied in Compass, you might need to rebuild plugins that you changed with the compile command. Instead of manually writing out the scope you might want to use lerna --since filter to rebuild everything since your local or origin HEAD of the git history: npx lerna run compile --stream --since origin/HEAD. Restarting or hard-reloading (Shift+CMD+R) Compass after compilation is finished should apply your changes.

In addition to running lerna commands directly, there are a few convenient npm scripts for working with packages:

• npm run compile-changed will compile all plugins and their dependants changed since origin/HEAD
• npm run test-changed will run tests in all packages and their dependants changed since origin/HEAD
• npm run check-changed will run eslint and depcheck validation in all packages (ignoring dependants) changed since origin/HEAD

When running Compass application or tests suites locally, you might run into errors like the following:

Error: Module did not self-register: '/path/to/native/module.node'.

Error: The module '/path/to/native/module.node' was compiled against a different Node.js version using NODE_MODULE_VERSION $XYZ. This version of Node.js requires NODE_MODULE_VERSION $ABC.

The root cause is native modules compiled for a different version of the runtime (either Node.js or Electron) that tries to import the module. In our case this is usually caused by combination of two things:

1. Modules have to be recompiled for the runtime they will be used in
2. Due to npm workspaces hoisting all shared dependencies to the very root of the monorepo, all packages use the same modules imported from the same location

This means that if you e.g., start Compass application locally it will recompile all native modules to work in Electron runtime, if you would try to run tests for mongodb-connection-model library right after that, tests would fail due to keytar library not being compatible with Node.js environment that the tests are running in.

If you run into this issue, make sure that native modules are rebuilt for whatever runtime you are planning to use at the moment. To help with that we provide two npm scripts: npm run electron-rebuild will recompile native modules to work with Electron and npm run node-rebuild will recompile them to work with Node.js.

For package changes to be applied in Compass beta or GA releases they need to be published first. The whole publish process happens from the main branch with the following command in order:

1. npm run packages-version [semver bump]: updates package versions for everything that was changed since the last release, updates package-lock file at the root of the repository, commits and tags the changes. See lerna docs to learn more about optional semver bump argument.
2. npm run packages-publish: publishes packages to the registry, if your npm account uses OTP publishing protection get ready to enter the code a few times, as an alternative you might want to use npm automation authorization tokens locally if OTP gets in the way too much (in that case add a --no-verify-access flag to the publish command). Publish command can be re-run safely multiple times, so if something bad happens mid-release (e.g., your internet goes out), you should be able to safely fiinish the process. After publish finishes successfully the script will push version update commit and tags created in step 1. We do it automatically only post-release so that when evergreen picks up a commit in the main branch, all the tasks can run with the packages already published.

To add, remove, or update a dependency in any subpackage you can use the usual npm install with a --workspace argument added, e.g. to add react-aria dependency to compass-connect and compass-query-bar plugins you can run npm install --save react-aria --workspace @mongodb-js/compass-connect --workspace @mongodb-js/compass-query-bar.

Additionally if you want to update a version of an existing dependency, but don't want to figure out the scope manually, you can use npm run where helper script. To update webpack in every package that has it as a dev dependency you can run npm run where "devDependencies['webpack']" -- install --save-dev webpack@latest

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

For contributing, please refer to CONTRIBUTING.md

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

SSPL