Creating custom node from subflow in Node-RED

In this article, I will introduce the development method of the Node-RED’s node from the subflow. Subflow is a component block that enables users to reuse flow by the same method as “function” in the general programming language. Using this subflow, Node-RED users can create custom nodes with flow development knowledge only.

In this blog, creating a subflow is the first step. After downloading the subflow as the JSON file to your local PC, you will put the JSON file in the GitHub repository. After that, the uploaded JSON file will be automatically converted to tgz file which includes the custom node by GitHub Actions. Finally, you will download the generated tgz file to your local PC, and then install it to the Node-RED environment to test the custom node.

Prerequisites

• GitHub account
  If you do not have a GitHub account, register an account on the website:
  https://github.com/signup
• Node-RED environment
  In the event that a Node-RED environment on a local PC or cloud is available, you can start to create a subflow right away. On the other hand, if you have no Node-RED environment, the following Gitpod environment is useful:
  https://gitpod.io/#github.com/node-red/node-red
  
  Once you log into Gitpod using your GitHub account, Node-RED will boot up automatically. After about one minute, the prompt confirming availability will appear on the bottom right of the Gitpod UI as follows.

After clicking the “Open Browser” button, a new tab will open and you can temporarily use the Node-RED environment.

Steps to create a custom node

The following procedures show a step-by-step guide on how to create the custom node. As an example, I used the `cowsay2` module to generate ASCII art that shows a cow saying something (See the video). Using this npm module, the custom node receives a text from the previous node in the flow and then outputs the ASCII art including the text to the next node in the flow.

1. Creating a flow

First, we need to create a flow from scratch. After placing the function node in the workspace of the flow editor, paste the following code into the text area inside the “On Message” tab.

— — — — — — — — — — — — — — — — — — — — —
msg.payload = cowsay2.say(String(msg.payload));
return msg;
— — — — — — — — — — — — — — — — — — — — —

To load the `cowsay2` module, input the `cowsay2` as the module name after clicking the “+add” button on the “Setup” tab of the function node.

In addition to the function node, connect the inject node and the debug node to complete the flow. Prior to executing the flow, click the deploy button to apply the flow to the backend.

After that, click the inject node button, and then you can see the ASCII art of the cow on the debug tab.

2. Converting the flow to subflow

Next, let’s create a new subflow from the defined flow. After selecting the function node, convert the selected node to a subflow by following these steps: Choose the Menu -> “Subflows” -> “Selection to Subflow”. In this case, the target flow is only a function node. Because of that, I selected a single node before manipulating it. If there are more than two nodes in the target, of course, you need to select multiple nodes.

As the result of this operation, the selected function node will be changed to a subflow.

After opening the subflow by double-clicking, you can see the node property of the subflow. In this node property, you can find the “Edit subflow template” button which shows the inside of subflow and where you can input some settings related to the custom node.

To be more exact, in the previous “Selection to Subflow” operation, the function node has been moved inside the subflow. Therefore, you can see the original function node after clicking the “Edit subflow template” button.

For the next step, click the “edit properties” button on the upper left of the flow editor.

3. Inputting node module information

In the `Name` field of the properties tab, enter `cowsay`. This name will eventually be used as the name of the generated custom node.

To configure the node module information, click the cube icon located at the bottom of the Cancel and the Done buttons. In the “Module properties” tab which opened after clicking the cube icon, specify the information of the custom node. This information is used in the package.json file of the custom node.

Because of the custom node policy, the “Module” should be a unique name that has a different name from custom nodes developed by other users and start with “node-red-contrib-”. Therefore, input “node-red-contrib-cowsay<your birthday>” to avoid conflict, for example. In addition to this naming policy, there is also a rule in “Keywords”. If you would like to publish your custom node in the Node-RED flow library, you need to add “node-red” into comma-separated keywords.

The followings are examples of the input.

• Module: node-red-contrib-cowsay<your birthday>
• Node Type: cowsay
• Version: 0.0.1
• Description: A node to generate ascii art using cowsay module
• License: Apache-2.0
• Author: Kazuhito Yokoi <kazuhitoyokoi@example.com>
• Keywords: node-red,cowsay

4. Exporting subflow as JSON file

To download subflow data to your local PC, select subflow on the central workspace at the first. And then, select “Export” from the menu of the flow editor.

Next, click the “Download” button existed on the “Export nodes” dialog.

After pushing the button, your browser will automatically download the “flows.json” file to your “Downloads” folder.

5. Importing the template to the GitHub repository

In this step, we will prepare a GitHub repository to store the “flows.json” file. By accessing the URL ( https://github.com/new/import ) on GitHub, you can see the following page for importing the existing repository.

To the “Your old repository’s clone URL” field, input “https://github.com/kazuhitoyokoi/node-red-contrib-template.git". This repository contains GitHub Action scripts for building custom nodes from subflow automatically. In the “Repository Name” field, input the node module name as the repository name. This should be the same as the module name specified in the node property of the subflow. Finally, click the “Begin import” button to execute importing process.

After the importing process succeeds, the following message will be shown.

In the above screenshot example, You can move to the created GitHub repository from the link which is “kazuhitoyokoi/node-red-contrib-cowsay0912”.

5. Uploading JSON file to the GitHub repository

In the imported repository, we can upload the flows.json file by browser operations. At first, click the “Add file” button and then select “Upload files” in the pull-down menu as you can see in the following screenshot.

In the next screen, drag the flows.json file to the central area or upload the file via the “choose your files” link. After the uploading flows.json file, click the “Commit changes” button to record the uploaded files in the version control system.

After these operations, you will see the uploaded flows.json file on the GitHub repository along with the “.github/workflows” directory and the “README.md” file.

6. Changing repository settings

In the imported repository, GitHub Actions is disabled as the default. Therefore, you need to enable the GitHub Actions and change permissions. To change the settings, click the “Settings” which has a gear icon. After moving to the setting page, you can see the general settings first. To move to the GitHub Actions configurations, open the “Actions” which has the play button on the left menu, and then select the “General”.

The above is the screenshot after the settings changed. As you can see from this screenshot, two permissions settings need to be changed. First, switch the radio button from “Disable Actions” to the “Allow all actions and reusable workflows” in the “Actions permissions” section. After that, click the “Save” button to apply the change.

7. Generating the custom node

As the next step, let’s release the custom node using the function of GitHub Release. Move to the top page of the GitHub repository from the “Code” menu located on the left.

On the top page, there’s a link, “Create a new release” in the lower-right “Releases” area. By this link, you can move to the release page of the repository.

To create the first tag of the release, click the “Choose a tag”, and then input “v0.0.1” which means the first release, click the “+ Create new tag: on publish”.

In the title of the release, enter the description like “v0.0.1: The First Release”, for example. Finally, push the “Publish release” button.

After the releasing procedure, the browser shows the following page. Immediately after release, the file list in the assets has only two source code files, both zip, and tar.gz firstly. However, the tgz file, “node-red-contrib-cowsay0912–0.0.1.tgz” which contains the custom node will be added within one minute. If you’re interested in the progress of generating the custom node, you can see the log of the process on the GitHub Actions page from the “Actions” button which has the play icon.

To download the tgz file to your local PC, click the link of the “node-red-contrib-cowsay0912–0.0.1.tgz”.

8. Importing the custom node to Node-RED

To test the generated custom node, we will install the tgz file to the Node-RED flow editor. Firstly, select the “Manage Palette” item on the menu, In the User Settings UI, next click the “Install” tab. Inside this tab, there’s a button to upload the tgz file to the Node-RED flow editor.

After uploading the file to the Node-RED flow editor, the new node which has an arrow icon has emerged in the function category of the palette.

Of course, the generated cowsay node works as same as the original subflow. Let’s try to create the flow.

Conclusion

In this article, I introduced how to generate a custom node from subflow. This development method is the easiest way to create a custom node for Node-RED. Additionally, using GitHub Actions, users also don’t need to set up development environments on their local PC.

I’m glad if you use this efficient development style when you create a custom node.