External Dependencies
On this page
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.
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.
Uploaded zip files are subject to a 10MB size cap.
Procedure
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.
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 .
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/
MongoDB Realm supports .tar, .tar.gz, and .zip archive
formats.
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:
- Select MongoDB Realm from the left-side navigation.
Select the Triggers_RealmApp app.
NoteTriggers created prior to 09 Jun 2020 use the name Triggers_StitchApp.
- Select Functions from the left-side navigation.
- Select the Dependencies tab.
- Click the Upload File button.
- In the file picker, select the
node_modules.tar.gzarchive 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. - 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.
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.
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.