How to integrate NodeJS modules with OutSystems
If you have seen the above message, you may have already been trying to integrate NodeJS modules and noticed require does not work on a browser or with OutSystems. But what is require?
Require is an asynchronous module loading mechanism.
On the browser, you need to include js code with <script> tags, you must ensure everything is loaded in the correct order and not loaded twice, you must ensure dependency integrity, etc. With require, you have it simpler: you just have to install the module, require, and start coding.
Require follows the AMD specification, which specifies a mechanism for defining modules such that the module and its dependencies can be asynchronously loaded, and through this specification, it handles a lot of complexity for us.
So one would ask, can’t I just use require on my OutSystems app and use it to load the NodeJS module I need?
Well, no. Put simply, require belongs to NodeJS, and NodeJS is server-side javascript. It would be like running a server inside your web page and you really don’t want to try that.
But there is a way to use all these NodeJS modules outside Node.
Browserify brings all the advantages of Require to your browser and will let you bundle up all your NodeJS code into a single bundle you can then use on your OutSystems application!
In this article, I will demonstrate exactly this: how to run NodeJS modules on your OutSystems app using Browserify!
Requirements
To proceed with this How-To, you will need the following:
- Have administrator privileges over your personal machine
- Have NodeJS installed on your personal machine
- Have permissions to execute scripts
To gain permission to execute scripts, execute the following command as an administrator on Powershell:
Set-ExecutionPolicy RemoteSignedAfter finishing your tasks, you should reset the execution-policy back to its default value:
Set-ExecutionPolicy RestrictedA sample problem
For this How-to, I will give you the example that triggered all my investigation.
I was trying to use the Markdown-it module from the forge, which is a react module that renders markdown text client-side.
Problem was, I needed to extend the functionality of Markdown-it to render images and a table of contents, which required me to install these 3 plugins:
And on the documentation of the plugins, there I saw the dreaded “require”:
If I just copy-paste this code into OutSystems and use it as is, I will get the “Uncaught ReferenceError: require is not defined” error. I will need to Browserify the plugins for it to work!
Browserify will bundle all my libraries into a single bundle I can then bring into OutSystems. With the plugins bundled and imported into OutSystems, I will be able to use them on my applications without issues.
Note: There were on some of the plugins instructions on how to use the plugins without require. But no matter how hard I tried, I simply could not get it to work. With Browserify it worked on my first attempt :)
Browserifying the plugins
Assuming you already have NodeJS installed, open up your Powershell, and change install Browserify:
npm install --global browserifyNow change the directory to your Documents folder:
cd DocumentsCreate a new directory for our project:
mkdir markdownit-outsystemsChange directory to the directory you just created (hint: use “Tab” to auto-complete):
cd .\markdownit-outsystemsAnd install the required modules (in this case, I need markdown-it and 3 plugins: anchor, toc-done-right, and linkify-images):
npm install markdown-it --savenpm install markdown-it-anchor --savenpm install markdown-it-toc-done-right --savenpm install markdown-it-linkify-images --save
Now, let’s navigate into the folder we just created using the file explorer:
And create a new “main.js” file. On this file we will do our requires and expose our node modules so we can use them in OutSystems:
On the above code, I’m requiring the libraries and then exposing my code by exporting a new Module named “MDOutSystems” with two functions: render and getInstance. I need to expose the module and functions because all code bundled using Browserify and not exposed will be scoped under the bundle and thus unavailable to the “outside world”. To ensure my module is available on the outside I also need to use the “standalone” option when generating the Bundle.
To generate the bundle, we run on the console:
Browserify main.js --standalone MDOutSystems > markdown-it-outsystems.jsWith this line of code, I’m using my main.js file to generate a bundle named “markdown-it-outsystems.js” that contains all my code and required modules on main.js, while exposing the MDOutSystems module, as seen below:
I’m now able to use the “markdown-it-outsystems.js” js file and my MDOutSystems module on any browser!
To test if it is working, I created a simple “index.html” web page on the same folder:
And by opening my page on chrome, I test it and:
Success! I now have a bundle I can use on OutSystems with all nodeJS code I need.
Using the Browserified bundle on OutSystems
Here, the process is the same as integrating with any Javascript library.
We import the javascript:
We make sure we import it on our block:
We call the functions:
Et voila! Done!
Files
Acknowledgments
Big thanks to those who shared their knowledge with the world and allowed me to quickly understand the why’s, what’s, and how’s of both require and Browserify:
Getting Started with Browserify — By Peleke Sengstacke
Exposing a Javascript API in a Web Page with Browserify — By Ryan Daigle