Chapter 13: Creating and Publishing Your Own Node on the Node-RED Library

So far, we have learned about Node-RED using the prepared nodes. In this chapter, you'll learn how to create your own node and publish it in a library. After completing the tutorials in this chapter, you will be able to publish your own node for use by various developers around the world.

Let's get started with the following topics:

• Creating your own node
• Testing your own node in a local environment
• Publishing your own node as a module on the Node-RED Library

By the end of this chapter, you will have mastered how to create your own node.

Technical requirements

To progress in this chapter, you will need the following:

• A GitHub account: https://github.com/.
• An npm account: https://www.npmjs.com/.
• Node-RED (standalone in a local environment).
• An IBM Cloud account.
• The code used in this chapter can be found in Chapter13 folder at https://github.com/PacktPublishing/-Practical-Node-RED-Programming.
• The steps of this tutorial are basically processed on Mac. If you use a Windows PC, please replace the commands and file path with your environment.

Creating your own node

Before developing a node, there is something you need to know first. The following policies are set for node development. Let's follow these and develop a node.

When creating a new node, you need to follow some general rules. They adhere to the approach adopted by the core nodes and provide a consistent user experience.

You can check the rules for creating a node on the official Node-RED website: https://nodered.org/docs/creating-nodes/.

Node program development

Node-RED nodes consist of two files: a JavaScript file that defines processing and an HTML file that provides a UI such as a setting screen. In the JavaScript file, the processing of the node you create is responsible for is defined as a function. This function is passed an object that contains node-specific properties. The HTML file describes the property settings screen displayed by the Node-RED flow editor. The settings values entered on the property settings screen displayed in this HTML file are called from the JavaScript file and processed.

Here, we will create a GitHub repository, but if you just want to create a node, you don't need a GitHub repository. In this chapter, we will use the GitHub repository to publish the created node to the library, so I would like you to create the repository at the beginning of the step.

Please implement the following steps to create a GitHub repository:

1. Go to https://github.com/ and log in with your GitHub account.
2. Select New repository from the + dropdown at the top right of the GitHub page:
   

   Figure 13.1 – Create a repository for your own node

   The repository created here exists as a project for developing nodes, and then it will be packaged and published to npm. (Of course, it is optional to publish it.)

   Therefore, make sure that the repository name follows the naming convention for node development.

   The GitHub repository name will be the same as the node name. In the node creation rule, the node name must be node-red-contrib-<name representing a group of nodes>, so specify the GitHub repository name accordingly. In this example, it is node-red-contrib-taiponrock.

3. After specifying the repository name, set the repository disclosure range to Public, check the README file, and specify the license. In this example, it is created with the Apache License 2.0.
4. After setting everything, click the Create repository button to create a repository:

Figure 13.2 – The repository is created as a public project

You have now created your GitHub repository.

Now let's clone the repository we just created to our local development environment by following these steps:

1. Copy the repository URL to the clipboard. Click the green Code dropdown and click the clipboard button to copy the URL:
   

   Figure 13.3 – Copy the URL to clone this repository

   Clone the repository locally (git clone) from a command-line interface (such as a terminal) where Bash can run.

2. Go to the working directory where you want to clone (copy) the repository. Here, I created a work directory under the user directory and moved to it:

   $ mkdir work

   $ cd work

3. Execute the git clone command with the URL of the repository you created earlier:

   $ git clone https://github.com/<GitHub account>/node-red-contrib-<Any specified string>.git

4. When the clone is finished, use the ls command to confirm that it has been successfully cloned:

   $ls

   node-red-contrib-<Any specified string>

   Let's make a JavaScript file now.

   From here, we will create the actual node processing. But don't worry, we already have the code ready. The provided code is very simple for processing the node. It's just a matter of converting the string passed as input to lowercase.

5. First, change to the directory of the cloned repository:

   $ cd node-red-contrib-<arbitrary specified string>

6. Under this directory, create a file with the filename node.js, as shown in the following code:

   module.exports = function(RED) {

       function LowerCaseNode(config) {

           RED.nodes.createNode(this,config);

           var node = this;

           node.on('input', function(msg) {

               msg.payload = msg.payload.toLowerCase();

               node.send(msg);

           });

       }

       RED.nodes.registerType("lower-case",LowerCaseNode);

   }

   node.js has been created.

   Let's make an HTML file now.

7. Create a file under the same directory with the filename node.html, as shown in the following code:

   <script type="text/javascript">

       RED.nodes.registerType('lower-case',{

           category: 'function',

           color: '#a6bbcf',

           defaults: {

               name: {value:""}

           },

           inputs:1,

           outputs:1,

           icon: "file.png",

           label: function() {

               return this.name||"lower-case";

           }

       });

   </script>

   <script type="text/html" data-template-name="lower-case">

       <div class="form-row">

           <label for="node-input-name"><i class="icon-          tag"></i> Name</label>

           <input type="text" id="node-input-name"           placeholder="Name">

       </div>

   </script>

   <script type="text/html" data-help-name="lower-case">

       <p>A simple node that converts the message payloads         into all lower-case characters</p>

   </script>

   node.html has been created. This HTML file is responsible for the UI and design of the node you create. As mentioned previously, a node always consists of an HTML file and a JavaScript file.

The node implementation has been almost completed. Next, let's package the created node so that it can be deployed.

Node packaging

Now that we've created the node processing (JavaScript) and appearance (HTML), it's time to package it. In Node-RED, the flow editor itself is a Node.js app, and each node running on it is also a Node.js app. In other words, the packaging here is processed using npm.

We won't go into detail about npm here. If you want to know more about it, please visit the npm official website or refer to various technical articles: https://www.npmjs.com/.

Now, use the npm command to perform the following steps:

1. npm initialization. Execute the following command in the same location as the directory where node.js and node.html were created:

   $ npm init

2. When you run npm init, you will be asked for various parameters interactively, so enter them according to how you want to proceed. These are the parameters that I used:
   

   When you finish this step, the npm init command will generate a package.json file:

   

   Figure 13.4 – npm init

3. Edit package.json. You will need to manually add Node-RED-specific settings to package.json. Open the package.json file with a text editor and add the new property at the same level as "name" and "version" in the JSON: "node-red": {"nodes": "{" lower-case ":" node.js "} }:

   {

      "name": "node-red-contrib-<arbitrary string      specified>",

      "version": "1.0.0",

      (abridgement)

      "node-red": {

        "nodes": {

          "lower-case": "node.js"

        }

      },

      (abridgement)

   }

   The following screenshot can be used as a reference, which will help you in adding this property:

Figure 13.5 – Edit package.json

This completes the packaging of your own node. Let's actually use this node in the next part.

Testing your own node in a local environment

You have already completed your own node. Let's add the nodes created so far to Node-RED in a local environment.

For your own nodes, it is very important to check their operation locally. Publishing a node on the internet without making sure it works in your environment is not good for many developers.

So, in this section, you'll be testing your own node in your local environment.

Node installation

You can use the npm link command to test the node module locally. This allows you to develop nodes in your local directory and link them to your local Node-RED installation during development.

This is very simple. Follow these steps:

1. Execute the following command on the CLI to add a node and start Node-RED:

   $ cd <path to node module>

   $ npm link

   This will create the appropriate symbolic link to the directory and Node-RED will discover the node at boot time. Simply restart Node-RED to get the changes to the node's files.

2. Run the node-red command on the command line to start the local Node-RED. If it has already been started, restart it.

   You should see that a node called lower case has been added to the function category of the palette after rebooting:

   

   Figure 13.6 – The lower case node has been added

3. Let's see if it can be used properly. Create a flow by sequentially connecting each node of inject lower case debug.
4. For the properties of the inject node, set it to the character string type and set it to output any character string in all uppercase letters, for example, MY NAME IS TAIJI:
   

   Figure 13.7 – Make a flow

5. When you deploy the created flow and execute the inject node, you can see that the all-uppercase string, as the parameter of this flow, is converted to an all-lowercase string and output to the debug tab:

Figure 13.8 – Result of this flow

Next, let's see how to customize a node.

Node customization

I was able to confirm that the node I created can be used in the local environment. From here, we will customize that node. It is possible to edit the function and appearance of the node by modifying JavaScript and HTML. These changes will take effect when you restart Node-RED.

Changing the node name

Currently, the node name of the created node is still a lower-case version of the sample program. Here, change this name to any name you like. Every node must have a unique name, so you should pick something that does not already exist. Follow these steps to change the name of the node:

1. Change lower-case described in the package.json file to your own node name.

   In the example, the repository of the node is node-red-contrib-taiponrock, so change it to the taiponrock node.

   This is how the package.json file looks before being modified:

   

   Figure 13.9 – Before modifying package.json

   And this is how it looks after being modified:

   

   Figure 13.10 – After modifying package.json

2. Change lower-case and LowerCaseNode described in the node.js file to your own node name.

   For example, change lower-case to taiponrock and LowerCaseNode to TaiponrockNode.

   This is how the node.js file looks before being modified:

   

   Figure 13.11 – Before modifying node.js

   This is how the node.js file looks like after being modified:

   

   Figure 13.12 – After modifying node.js

3. Change lower-case described in the node.html file to your own node name.

   For example, change lower-case to taiponrock.

   This is how the node.html file looks before being modified:

Figure 13.13 – Before modifying node.html

This is how the node.html file looks after being modified:

Figure 13.14 – After modifying node.html

After restarting Node-RED, you can see that it has been renamed correctly:

Figure 13.15 – Your node has been renamed

Next, we will see how we can change the code of a particular node.

Changing the node code

The main parts that implement node processing are as follows:

1. Change the code. You can change the processing of the node by rewriting msg.payload = msg.payload.toLowerCase (); defined in this part of node.js:

   (abridgement)

   node.on ('input', function (msg) {

        msg.payload = msg.payload.toLowerCase ();

        node.send (msg);

   }

   (abridgement)

   Here, to make the work easier to understand, let's change to a method that only returns the character string of your name or nickname.

2. Let's rewrite node.js as follows:

   (abridgement)

   node.on ('input', function (msg) {

        msg.payload = "Taiponrock";

        node.send (msg);

   }

   (abridgement)

3. Execute the flow.

   Now let's see if it has changed. Use the flow you created earlier. The lower case node in this flow has been changed to a node whose name and processing has been changed, but it needs to be redeployed and raised. To make it easier to understand, delete the node that was once the original lower case node and relocate it.

   

   Figure 13.16 – Replace the node you created with the renamed node and execute it

4. Check the result. When you deploy the created flow and execute the inject node, you can see that the character string (name or nickname) that was set as a constant in this Changing the node code section is displayed in the debug tab.

Figure 13.17 – Result of this flow

In the next section, we will see some other node customizing options that we can use.

Other customizing options

In addition to the node name, you can customize your own node in a lot of different ways, such as node color, node icon, node category, node function, and so on. For details, please see this official document: https://nodered.org/docs/creating-nodes/appearance.

Now that we have tested and customized the node in the local environment, let's publish the node in the Node-RED library.

Publishing your own node as a module in the Node-RED Library

Here, we will publish the created node in the Node-RED library. To do that, some work is required. So far, you have created your own node and confirmed that it can be used only in your environment. However, since it is a unique node created by you, let's publish it on the internet and have everyone in the world use it. To do this, you need to publish your own node to a location called the Node-RED library, which can be found here: https://flows.nodered.org/.

Important note

The Node-RED library is a community-based place to publish nodes and flows. Therefore, you should avoid exposing incomplete or useless nodes. This is because the Node-RED users should be able to find the nodes that they want, and it is not desirable to have a mix of unwanted nodes.

So, although this chapter will explain how to publish nodes, please avoid exposing test nodes or sample node-level ones.

Publishing the node you created

Follow these steps to publish your own node in the Node-RED library:

1. Maintain a README.md file.

   We will write the node description in the README.md file. English is the best language to write in, considering that English is a universal language.

   For example, it is desirable to describe the following contents:

   • Overview explanation
   • How to use the node
   • Screenshot
   • Sample flow using this node
   • Prerequisite environment
   • Change log

     In this section, since it is a hands-on tutorial, only the outline and usage will be written in the README.md file. Please update README.md with the following contents:

     # node-red-contrib-<Any specified string>

     ## Overview

     This node is a node for forcibly converting all the alphabet character strings passed as input to the character string "Taipon rock".

     Even if the input parameter passed is not a character string, "Taiponrock" is forcibly returned.

     In this process, it is a wonderful node that changed the sample node that was executing toLowerCase, which is an instance method of String object in JavaScript, to a process that just returns a meaningless constant.

     ## how to use

     It is used when you want to forcibly convert all the character strings of the parameters to be passed to "Taiponrock".

2. Upload files – make sure you have five files: node.js, node.html, package.json, README.md, and LICENSE in the directory (it doesn't matter if package.lock.json is included):
   

   Figure 13.18 – Check these five files

   Upload these files to the repository on GitHub. You should have done the work in the cloned repository directory, but if you are in another location, move to that repository directory. Then, execute the following command:

   $ git add .

   $ git commit -m "Node has been published"

   $ git push

   When the push finishes without error, you can see that the target file has been uploaded in the repository on GitHub:

   

   Figure 13.19 – Your node files are uploaded

3. Publish your node (npm publish).

   Now let's expose the node as a module. Upload the set of files using the npm command. Again, work in the cloned repository directory:

   $ npm adduser

   $ npm publish

   You will be asked to confirm the version when you run npm publish. Don't forget to edit package.json to increase the version number, as the version must be up when you run npm publish a second time or later.

   When publish is completed normally, it will be published at https://www.npmjs.com/package/node-red-contrib-<arbitrary character string>.

   An example is https://www.npmjs.com/package/node-red-contrib-taiponrock:

   

   Figure 13.20 – Your node has been published on npm

4. Register the created node from Adding a node of the Node-RED library.
5. In Add your node to the Flow Library, enter the name of the node you created and click the add node button:

Figure 13.21 – Add your node to the Node-RED library

When the registration is complete, you can see that the created node has been added to the library:

Figure 13.22 – Your node has been published in the Node-RED library

It takes about 15 minutes for the registration of a new node. Please note that the node you registered via the Node-RED flow editor cannot be found without complete registration on the Node-RED library.

If you upgrade the version and publish it again, please refresh from your node's page of the Node-RED Library and click check for update in the Actions panel on the right side of the node screen:

Figure 13.23 – Check for the update of your node's status

Next, let's see how to delete the node published by you.

Deleting the node you published

Be careful when deleting published nodes. Currently (as of October 2020), according to npm's package unpublish policy, the unpublish deadline is within 24 to 72 hours of publication. In addition, it is possible to unpublish packages that have little effect on specific conditions, such as less than 300 downloads even for 72 hours or more.

This information is expected to be updated from time to time, so please refer to the npm official website for the latest information: https://www.npmjs.com/policies/unpublish.

After unpublishing, please refresh from your node's page of the Node-RED library in the same way as when updating. Click the request refresh at the bottom of the Actions panel on the right side of the node screen.

To unpublish, execute the following command in the module directory (the directory of the cloned repository):

$ npm unpublish --force node-red-contrib- <arbitrary string>

If this command completes successfully, the module unpublishing is successful.

Installing the node you published

It is recommended that you wait at least 15 minutes after completing adding your node to the Node-RED Library.

In Node-RED of the local environment, I reflected the self-made node so that it can be used as it is. I also published it to npm for publication and registered the node in the Node-RED library. Anyone should now be able to use this node.

Here, let's try and check whether the node created this time can be installed and used without any problems from Node-RED of IBM Cloud. Please follow these steps:

1. Log into IBM Cloud, create a Node-RED service, and launch the Node-RED flow editor.
2. Open Manage Palettes in the flow editor:
   

   Figure 13.24 – Access ing Manage palette

3. Select the Install tab and start typing the name of your node you created in the search field.

   If the node you created is displayed in the search results, it means that it is open to the public and is the target of installation.

4. Click the Install button to install.

   If it is not displayed in the search results, you must have not waited for 15 minutes after node registration. Please try again after 30 minutes or 1 hour. If you still do not find your node, there may be some other cause, so please review the procedure you have done so far and try again:

   

   Figure 13.25 – Search for and install your node

5. Confirm that the node you created on the palette is installed, create a flow as shown in the following figure, and execute the inject node:
   

   Figure 13.26 – Make the flow

   In the example, the self-made node is inserted between the flows prepared by default when the Node-RED flow editor is started for the first time.

6. After running the inject node, verify that the results are displayed in the debug window:

Figure 13.27 – Result of this flow

Great job! You now know how to make your own node and publish it.

Summary

Congrats! In this chapter, you learned how to create your own node, how to customize it, and how to set it from the Node-RED library or your local machine. Creating your own node wasn't as difficult as you might think. If you create the processing content and arrange the appearance based on this procedure, you can publish your own useful node that does not already exist and have developers all over the world use it!

Also, at the end of this book, I'll give you a brief introduction to the Node-RED user community, so be sure to check that out as well.