How To Write a CONNECT platform Package

CONNECT platform packages are simple NodeJS packages that allow you to expand what you (and your fellow developers) can do with CONNECT platform. As discussed here, you can already add any Javascript code snippet to your platform if need be, and that ability, combined with the fact that the platform utilizes NPM as its package-manager under the hood, allows you to utilize any functionality of any NPM package on your instances.

However, it might be a neater idea to wrap a Javascript module to create a proper CONNECT platform package for more convenience. In this guide we explore how you can do that, utilizing the boilerplate project for creating a CONNECT platform package.

Setup

1 Clone the CONNECT platform package boilerplate, and rename the folder to what you want your package to be named:

> git clone https://github.com/loreanvictor/connect-platform-package-boilerplate.git
> mv connect-platform-package-boilerplate tutorial-package

2 Add a git repository (this step is obviously not necessary, but its smart to do this). I will create a public GitHub repo for this tutorial:

It is highly recommended to NOT initialize a README file or any other files, as the boilerplate package has everything necessary. Now you need to change the repo of the cloned code to the one you just created:

> cd tutorial-package
> git remote set-url origin https://github.com/loreanvictor/tutorial-package.git
> git push

which should cause your GitHub repo to look like this (on refresh):

3 Update your package.json file. Update the "name" , "description" , "repository" , "author" and the "bugs" fields. You might also want to update "version" and perhaps "license" if you want to use a different license for your package. In the end, it should be updated to look something like this:

It is also a good idea to recreate your package-lock.json :

> rm -f package-lock.json
> npm i

If you are a good open-source samaritan perhaps you should update README.md as well.

Development

So now that you have your setup ready, lets discuss how you can start developing a package.

As mentioned earlier, CONNECT packages are nothing but simple Javascript modules, with some additional flavor. On the most basic level, a package is a Javascript code that registers some platform Nodes (if you have no idea what Nodes are, maybe check this doc first). For example, this code snippet does that in the simplest possible manner:

This simply registers a Node on path /my-package/hellow that gets a name as an input and returns a greeting to that name. You can take a look at hellow.js in your boilerplate setup for much more in-depth information, for example on what options you have for the signature object (the first parameter in platform.node() call in the code snippet above) register your function with.

You can register any function using platform.node() . The function you register will be invoked whenever there is a Call to the path you register it on. If you provide a function f() , then it will be called like this:

f(inputs, output, control, error);

Where

• inputs is a dictionary of all given inputs,
• output is a function that you can call to send an output. It takes two arguments, first the name of the output, and the second its data. The name of the output should match one of the strings in "outputs" field of the signature object.
• control is a function similar to output, but for activating control outputs instead of normal outputs (or to send signals instead of data as a result of the execution of your Node, for example a simple “success” flag without additional data). It gets one input, which is the name of the control output to be activated, and it should match one of the strings in "controlOutputs" field of the signature object.
• error is a function that you can use to throw errors. It is really important to use this function instead of just throwing an error specifically when you have asynchronous calls, as although the platform will try its best to catch all errors that might stem from your code, it might not be able to catch the ones resulted in asynchronous calls. So make sure you have proper error handling (sync or async) in your code and that you pass the caught errors to this function (or you can simply pass a string indicating the nature of the error).

That is basically it. The boilerplate package you already cloned is a simple “hellow world” package with lots of comments to explain everything in code, and you can also check out this or this package as for more complex examples.

But How To Test It?

The package boilerplate installs connect-platform as a dev dependency and configures it so you can easily test the Nodes you add in the platform. Simply run this:

> npm start

and checkout localhost:4000/panel to see your test area. For example, you can test the Node described in hellow.js like this:

Package Configuration

Perhaps you have noticed that the hellow.js in the boilerplate code is actually not the entry point of your package (in package.json ). Although in theory, you could make a file like that and set it as the entry point of your package, which would actually function as a proper CONNECT platform package, it is almost always a better idea to add some configuration info to also tell the platform how to load your package and where everything belongs.

If you take a look at the actual entry point of your boilerplate package, which is index.js , you will see something like this:

Which basically should explain how to configure your package :) Just a few notes:

• The "nodes"."native" field in your configuration will basically tell the platform to simply require the given files. It will of course search in a different order compared to require() ‘s default behavior, prioritizing the root of your package. It will also map which Nodes are loaded by each package.
• You can also load Nodes that you have created by the platform itself, which are stored in JSON format, using the "nodes"."json" field in your configuration. Except from, well, parsing the JSON file, this behaves exactly as native modules.

Publishing

If you want to make it accessible through NPM for all other developers like you, simply do this:

> npm publish

(Note that you don’t need to do that to be able to access a package you have made on your own CONNECT instances. CONNECT platform utilizes NPM to install packages, so you can easily install any Git repository as well, even private ones).

Now everyone can install your package by going to the “Packages” section of their platform, click on “Install From NPM” and enter the name of your package:

If you want your package to appear on the first screen, looking gloriously with its icon and description, then you need to create a pull-request for the CONNECT platform’s package repository, which is an open-source project as well. Simply update the repo.json file, by copying another one of the packages and modifying it to reflect your own package, and make a pull-request. The moderators will take a look and approve your package.