Node generator / template for Node-RED

This repository provides a starting point (a generator with templates) for writing custom nodes for Node-RED using TypeScript and ES6 classes instead of bare Javascript. It also makes an effort to automate away a lot of boilerplate for the packaging up your node, as well as enabling easy testing with VSCode Dev Containers.

See Why pick me for more of what this particular generator has to offer.

Make a node

So you want to build a node? It's Super Easy™.

Dependencies

• Docker (Docker Desktop on Windows is fine, but it must be running in WSL2 mode.)

Quick start

Note: These steps will walk you through creating a basic package called bobs-iot-devices. Obviously, change that to something to better reflect what you want to build. (Don't put node-red- in front of the name though except where specified.)

1. Fork this repo and clone it.
   git clone https://github.com/<your-username-here>/<your-repo-here>.git

   • Name it something to do with the node(s) you're going to create, e.g. node-red-bobs-iot-devices.
   • (You don't strictly need to fork if you just want to do local development. If that's the case, just clone this repo directly.)

2. Start up VSCode and open your newly cloned folder.

   • (On Windows, I start with the folder in a WSL window Command Palette -> Remote-WSL: New WSL Window. I'm not certain that's necessary unless you've cloned the repo in the WSL filesystem, but I tend to do it that way.)

3. Restart in a Dev Container. You may get prompted to do this automatically. If not:
   Command Palette -> Remote Containers: Open Workspace in Container

• Here's where the good stuff starts!

4. Generate the basic package.json and tsconfig.json.

   ./generate.js generate packageJson -name "bobs-iot-devices" -author "Your Name <your@email.here>"

   • For more arguments to ./generate.js, see Generator syntax or just run ./generate.js with no arguments

5. Generate your first node!

   ./generate.js generate node -name "bobs-sensor"

   • This will populate a folder bobs-iot-devices with views, locales, and icons.
   • If you want to generate another node, just run the command with a second name.

6. Compile everything. You can either do it:

   • via the GUI: Command Palette -> Run Task -> Compile TS or
   • in the terminal: npm run compile:all

7. Launch Node-RED!

   • Run -> Start Debugging

8. Check out your new node at http://localhost:1880! Look for "Some Node" at the bottom of the Node-RED palette.

Customizing your node

There are a few files that get created for each node that you will want to change to do anything interesting.
(Replace bobs-iot-devices and bobs-sensor with your package and node name.)

<style type="text/css"> DL.files DT { font-weight: normal !important; font-style: normal !important; font-size: medium; !important; font-family: monospace } DL.files DD { font-size: medium !important; } </style>

bobs-iot-devices/

bobs-iot-devices-bobs-sensor.ts

Core node definition. This is where the ES6 class lives that replaces the normal .js file. There is some magic at the bottom starting with module.exports. Don't touch that part!

If your node should store more settings than a name, update BobsSensorDefaults.

Everything else is inside the BobsSensor class, and because of the fanciness in the ES6 shim that makes this work, you should get IntelliSense autocompletion etc. The basic node template that is provided includes an example of listening for an incoming message and sending it along with the topic updated to Hello World.

views/

These files are compiled into the view file (the .html file that is a companion to the .js file.).

bobs-iot-devices-bobs-sensor.ts

This is the TypeScript file that is compiled into the view file and initializes the node. This is where you can configure most of the appearance of the node in the Node-RED editor.
Do note the support for localization using the this._ function.

bobs-iot-devices-bobs-sensor.html

This is the HTML file that renders the node details (the panel shown in the Node-RED editor when you double-click a node.) The template shows a simple example of an input field for changing the node's name. The input field is mapped to the node's name in the node's config object passed to the constructor using the id field, where the format is node-input-<varname>.
Do note the support for localization using the data-i18n attribute.

bobs-iot-devices-bobs-sensor.help.md

This is the help file for your node that shows up in the Node-RED editor. See the official help style guide.
You can rename this file to end it .html if you'd rather write your help in HTML instead of Markdown. You can delete this file if you don't want to provide help.

locales/en-US/bobs-iot-devices-bobs-sensor.json

This is where you can define localization strings used by the views. If you want to add additional languages, you'll need to create new subfolders, e.g. es-MX.

icons

This is where you should place any icons. The basic node generator will by default copy home.svg which is used by the template node. You can also use the built-in icons, update icon in the views/<node>.ts file, and delete this folder or its contents.

Generator syntax

TODO

Why pick me?

• VSCode Dev Container support:
  • Test locally! Iterate often!
• Full-featured TypeScript support:
  • For both the backend node and the frontend JS.
• Generate and publish a hello world node without writing any code!
• Views rendered from separate HTML, TypeScript, and Markdown/HTML (for help) files so syntax highlighting "just works."
• Template tests! (Coming soon...)
• Watch/auto-build (Coming soon...)