How To Write a CONNECT platform Package
1 Clone the CONNECT platform package boilerplate, and rename the folder to what you want your package to be named:
> 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
"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
> rm -f package-lock.json
> npm i
If you are a good open-source samaritan perhaps you should update
README.md as well.
So now that you have your setup ready, lets discuss how you can start developing a package.
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);
inputsis a dictionary of all given inputs,
outputis 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.
controlis 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.
erroris 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
localhost:4000/panel to see your test area. For example, you can test the Node described in
hellow.js like this:
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:
"nodes"."native"field in your configuration will basically tell the platform to simply
requirethe 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.
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.