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.
So you want to build a node? It's Super Easy™.
- Docker (Docker Desktop on Windows is fine, but it must be running in WSL2 mode.)
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.)
-
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.)
- Name it something to do with the node(s) you're going to create, e.g.
-
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.)
- (On Windows, I start with the folder in a WSL window
-
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!
-
Generate the basic
package.json
andtsconfig.json
../generate.js generate packageJson -name "bobs-iot-devices" -author "Your Name <[email protected]>"
- For more arguments to
./generate.js
, see Generator syntax or just run./generate.js
with no arguments
- For more arguments to
-
Generate your first node!
./generate.js generate node -name "bobs-sensor"
- This will populate a folder
bobs-iot-devices
withviews
,locales
, andicons
. - If you want to generate another node, just run the command with a second name.
- This will populate a folder
-
Compile everything. You can either do it:
- via the GUI:
Command Palette -> Run Task -> Compile TS
or - in the terminal:
npm run compile:all
- via the GUI:
-
Launch Node-RED!
Run -> Start Debugging
-
Check out your new node at http://localhost:1880! Look for "Some Node" at the bottom of the Node-RED palette.
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.)
- 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 withmodule.exports
. Don't touch that part!
If your node should store more settings than aname
, updateBobsSensorDefaults
.
Everything else is inside theBobsSensor
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 thetopic
updated toHello 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 thethis._
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'sconfig
object passed to the constructor using theid
field, where the format isnode-input-<varname>
.
Do note the support for localization using thedata-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, updateicon
in theviews/<node>.ts
file, and delete this folder or its contents.
TODO
- 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...)