Using modules and third-party libraries in Parse Cloud

Parse Cloud Code is the easy way to implement some custom logic outside our web or mobile application like custom validation, pre-filtering resource collections or sending a text notification when some conditions are met.

Once our codebase grows, we usually split the code to modules, decide to use some libraries from the NPM and integrate with third-party services. For this purpose, Parse Cloud allows us to use the CommonJS syntax but we have to manually add all thid-party libraries to the cloud folder alongside our own code and use a different from node.js convention for module identifiers.

For example if we want to use the lodash utility library, we need to place the bundled library in the cloud folder and require it:

var _ = require('cloud/lodash');

This has some serious drawbacks:

• we can’t really use NPM for dependency management and we have to include thir-party libraries in the project repository,
• if a third-party library requires some other modules it starts to be a bit tricky,
• prefixing each module identifier with cloud makes unit testing cumbersome and doesn’t play well with code assistance in IDEs,

The solution is obvious — we have to bundle our modules and all their dependancies before uploading them to Parse.

Setup

An example setup with Browserify allows to use the regular node.js paths making development a lot esier. And with Browserify transforms, we can even use the es2015 syntax (babelify) or some Handlebars templates (hbsfy).

Starting a Parse Cloud project using their CLI is well described in the Parse Cloud documentation so I‘ll skip this part.

After creating a new Parse project, we have to create a package.json file and rename the cloud folder to something else, for e.g. src. Our directory structure should look like this:

├── .gitignore
├── config
│ └── global.json
├── package.json
├── public
│ └── index.html
└── src
│ └── main.js

Now we have to install Browserify:

$ npm install browserify --save-dev

and add node_modules and cloud folders to the .gitignore file.

We can also add some NPM scripts to automate the build and deploy process. We do that in the scripts section of the package.json file:

"scripts": {
  "postinstall": "npm run setup",
  "setup": "npm run clean && mkdir cloud",
  "clean": "rm -rf cloud",
  "build": "browserify src/main.j --exclude buffer -o cloud/main.js",
  "deploy": "npm run build && parse deploy"
},

Did you notice the --excule buffer option? Parse provides their own implementation of Buffer that is a subset of the node.js Buffer and is made to work in the Parse environment so we have to tell Browserify not to include a buffer shim.

After adding these scripts we can run them like this:

$ npm run setup
$ npm run deploy

The first command will create a new cloud directory in our project and the second will bundle our code and upload it to Parse.

Parse Cloud Modules

Parse provides several libraries that are customized to work in Parse Cloud environment. There are modules for common APIs, so we can easily use Mailgun or Twilio. But if we need to integrate with a service provider that is not on the list, we’ll have to implement this on our own using Parse Parse.Cloud.httpRequest function to call that providers API because a module from npm might just not work (Parse Cloud is not “real” node.js environment).

ES6 on Parse Cloud

Parse JavacScript SDK starting from version 1.6 is more ES6-friendly. There are a few big changes in 1.6 but as of today Parse Cloud does not support ES6. So if we want to use the ES6 module syntax, we still have to transpile our code with Babel before deployment and the easiest way is to use babelify transform.

Browserify supports a flexible transform system to convert source files. There are several ways to configure them but I’ll focus on the simplest one — the command line option.

To do so, install babelify module:

$ npm install --save-dev babelify

And then modify the build script:

"build": "browserify src/main.js --exclude buffer --t babelify --o cloud/main.js"

Conclusion

With this setup we can easily split our code into modules, require external libraries, use NPM for dependency management, IDE code related features work as they should and we can use transforms for Browserify. We can now also easily lint, unit test our modules and deploy to Parse or automate those tasks using a CI server.

Using such setup greatly increases productivity in projects that use Parse Cloud and in my opinion solves some main problems related to modules in Parse. Moreover, Browserify can easily be replaced with any other bundling tool like Webpack.

I’ve pushed an example project to GitHub. Give it a try and let me know what you think.