Skip to content

Create a custom Node RED node (DRAFT)

Jump to bottom
bartbutenaers edited this page Dec 29, 2018 · 3 revisions

When custom functionality in Node-RED is required, most users will start writing Javascript code into a Function node. However creating a custom node from this code, will offer some extra advantages (compared to a Function node):

  • It can easily be shared with other users (via NPM and the 'Manage Palette' menu in the flow editor).
  • It can be customized by the user, via the node's config screen.
  • It can be versioned, and users can optionally install older versions of the node.
  • It can use other NPM modules, which will be installed automatically as a dependency.
  • It can be debugged, which will simplify troubleshooting the code.
  • ...

CAUTION: Make sure the required functionality doesn't exist already in Node-RED (search on flows.nodered.org, search on the web ...). And perhaps something similar exists, but it isn't quite 100% what you are looking for. In that case it might be worth contributing to that other node, by creating a pull-request for that node. TODO explain pull request way of working

The next sections will explain step-by-step how to setup and develop a new custom node.

NPM and Github accounts

When developing custom nodes, you will need at least two (free) accounts:

  • Sign-up for an NPM account here.
  • Sign-up for a Github account here.

Create a Github repository

When sharing custom nodes with the community, the corresponding source code should be stored in a source control system. Indeed versioning the custom code offers a number of advantages:

  • The users can analyse the code, before installing it.
  • The users can see what has changed in a new version.
  • The users can create their own version of the custom node (by forking the Github repository to his own Github account).
  • The users can contribute their own new functionality to the custom node (by creating a pull request).
  • ...

The most common used source control system for Node-RED is Github. Create a Github repository (= repo) where you can store all the files (source code, html, icons, images, documentation, wiki pages, ...) for the custom node.

  • Normally a repository will be used to store the files of 1 single custom node.
  • However a repository can also be used to store the files of multiple custom nodes, if those nodes belong somehow together. But take into account that all those nodes will be installed, even if the user needs only one of these nodes (messing up the user's palette).

A Github repository can be created in a few steps, but please:

  • Make sure that the repository name starts with node-red-contrib-... (or node-red-contrib-ui-... for a dashboard widget node), which is a Node-RED convention!

  • Add a short description 'A Node Red node to ...' that explains in few words the usage of the node.

  • Most users will create a (free) public repository, since the code can be viewed by everybody.

  • Always add a README page that explains how the node can be used. Good documentation is a huge step forward for our users. The syntax for writing such a page is called Github markdown. Note that the same markdown syntax can be used to create wiki pages in your repository.

  • Select a license for your custom node. Most nodes will use 'Apache license 2.0' or 'MIT license'.

  • Make sure that irrelevant files (for example .log files) won't be installed afterwards by NPM in Node-RED. Since the custom node will run on top of NodeJs, the 'Node' option for GitIgnore should be selected:

    image

Create required files

You can now create the required files in the empty Github repository. For a basic custom node, the following files need to be created:

  • Javascript file that contains the Javascript code to be executed in your Node-RED flow (on the server).
  • HTML file that contains the HTML for the node's config screen in the flow editor, and all Javascript code that will be executed in the config screen (in the browser).
  • README file that contains documentation about the node.
  • Package JSON file that contains information (node version, dependencies, ...) used by NPM to install the node somewhere.

Advanced developers will use Git commands to create those files. However novice users can do this easier in the Github web interface, by clicking the 'Create new file' button.

Publish node on NPM

NPM is an platform to simplify sharing Javascript modules (called nodes) among users. NPM is also a command line tool, which is installed automatically when NodeJs is being installed.

As soon as the node is working fine, it is time to publish it on NPM (to be used by the community). This can be done on any system where NPM has been installed, since it will publish the files located in the Github repository. This means that the custom node files don't have to be available on the system itself...

  1. Make sure that a new version number has been updated in the package.json file, otherwise an error will occur.

  2. Logon to NPM by using command npm login, which will ask for your credentials (NPM user name, password, ...). Note that this is only required once, i.e. the first time that NPM is used on this system.

  3. Execute command npm publish https://github.com/<github user name>/<github repository name>/tarball/master, where you have to fill in your Github information.

  4. Check on https://www.npmjs.com/package/<package name> whether the new version has been published in the NPM registry. Note that this can take several minutes.

  5. Check on https://flows.nodered.org/node/<package name> whether the Node-RED registry has been detected the new NPM package version. Note that this can take up to one hour. If it takes much longer, you can logon (using your Github account) into this page and click the 'Request Refresh' button:

    image

  6. As soon as the Node-RED registry has detected the new package version, the custom node should be available also in the 'Manage Palette' menu of the Node-RED flow editor.

Clone this wiki locally