Navigation

External Dependencies

Overview

An external dependency is an external library that includes logic you’d rather not implement yourself, such as string parsing, convenience functions for array manipulations, and data structure or algorithm implementations.

You can upload external dependencies from the npm repository to MongoDB Realm and then import those libraries into your functions using standard JavaScript module syntax. To get started with external dependencies, check out the following guides.

Create Your Own Modules

Though most npm modules are written by third parties, you can create and publish your own npm modules to house logic specific to your application. You can make your modules available to the Node.js community or reserve them for private use. To learn more, see npm’s guide on Contributing packages to the registry.

Upload External Dependencies

You can upload npm modules into the MongoDB Realm application that houses your triggers and MongoDB Realm Functions. This allows functions in your application to depend upon external libraries.

To use external dependencies, upload an archive of an npm node_modules folder via the MongoDB Realm UI. Once uploaded, any MongoDB Realm Function can import and use any dependencies listed on the dependencies page of the MongoDB Realm UI.

External Dependency Size Constraints

Uploaded zip files are subject to a 10MB size cap.

Procedure

1

Install your dependencies locally.

To upload external dependencies to MongoDB Realm, you first need a local node_modules folder containing at least one Node.js package. You can use the following code snippet to locally install a dependency you would like to upload:

npm install <package name>

If the node_modules folder does not already exist, this command automatically creates it.

Alternative Methods of Installation

You can also configure a package.json and run the npm install command to install all packages (and their dependencies) listed in your package.json.

To learn more about npm and node_modules, consult the npm documentation .

2

Create a dependency archive.

Now that you’ve downloaded all of your npm modules, you need to package them up in an archive so you can upload them to MongoDB Realm. Create an archive containing the node_modules folder:

tar -czf node_modules.tar.gz node_modules/

Supported Archive Formats

MongoDB Realm supports .tar, .tar.gz, and .zip archive formats.

3

Upload the dependency archive.

Once you’ve created an archive containing your dependencies, all that’s left to do is upload them to MongoDB Realm. You can upload your dependency archive using the MongoDB Realm UI:

  1. Select MongoDB Realm from the left-side navigation.

  2. Select the Triggers_RealmApp app.

    Note

    Triggers created prior to 09 Jun 2020 use the name Triggers_StitchApp.

  3. Select Functions from the left-side navigation.

  4. Select the Dependencies tab.

  5. Click the Upload File button.

  6. In the file picker, select the node_modules.tar.gz archive you just created and click Open. MongoDB Realm automatically uploads the archive file, which may take several minutes depending on the speed of your internet connection and the size of your dependency archive. Whether the operation succeeded or failed, MongoDB Realm displays a banner indicating the success or failure of the operation. If successful, the Dependencies tab displays a list of the dependencies that you included in your dependency archive.

  7. If drafts are enabled, you will also need to click Review & Deploy in the banner to apply these changes. If drafts are disabled, the change will take effect within 5 to 60 seconds.

Now that your dependencies have been uploaded, try importing them into a Function.

Import External Dependencies

Once uploaded to your application, you can import npm modules listed on the dependencies page of the MongoDB Realm UI into your MongoDB Realm Functions.

Pre-requisites for Import

You must upload dependencies before you can import them.

Usage

You can import dependencies into any MongoDB Realm function using the require keyword inside of the exports function. You cannot use ES Module import syntax. You should import dependencies in the style of a node_modules module import, since MongoDB Realm does not support file or local module import. To learn more about require syntax, consult the Node.js documentation for the require keyword.

Where Do I Import Modules?

Node.js projects commonly place require statements in the global scope of each file, but MongoDB Realm does not support this pattern. You must place MongoDB Realm Function require statements within a function scope.

Import a Full Module

Below, you’ll find a simple example of a function that uses the require keyword inside a function to import the ramda module and call ramda’s map method:

exports = () => {
   const R = require("ramda");
   return R.map(x => x*2, [1,2,3]);
}

Import a Module Subfolder

The following example demonstrates how to use require to import a single submodule of an external dependency into a MongoDB Realm Function:

exports = function(arg){
   const cloneDeep = require("lodash/cloneDeep");

   var original = { name: "Deep" };
   var copy = cloneDeep(original);
   copy.name = "John";

   console.log(`original: ${original.name}`);
   console.log(`copy: ${copy.name}`);
   return (original != copy);
};

Constraints

External dependencies are subject to the following limitations:

  • Require statements must appear inside a function declaration, not outside it. MongoDB Realm does not currently support statements in the global scope.
  • MongoDB Realm currently supports a subset of Node.js built-in modules. For a list of supported and unsupported modules, see function constraints.