Create a CLI to scaffold Nodes

[AllanOricil]

The idea is to create some cli commands that would help people to start a new Node-red Node project.

obs: I'm trying to follow the same thing salesforce cli (sfdx) does. Command topics start with the resource name.
obs: we will need to have something to distinguish Node-red projects from others. In sfdx they use they own proprietary manifest called "sfdx-project.json". Why we need this? to later create a vscode extension that runs "when: node-red-project.json" exists in the cwd.

nodered node create --name my-new-node --description "my new amazing node"

or

nr node create --name my-new-node

or

npx create-node-red-node my-new-node

Running this command would scaffold a new node-red Node project with some pre-defined files and folder structure (to be defined).

As a suggestion, this could be the default folder structure:

└── my-new-node/
    ├── .husky/
    │   ├── commit-msg
    │   └── pre-commit
    ├── examples/
    │   └── README.md
    ├── nodes/
    │   ├── my-new-node/
    │   │   ├── index.js
    │   │   ├── index.html
    │   │   └── assets/
    │   │       ├── custom-icon.svg
    │   │       ├── some-stylesheet.csv
    │   │       └── README.md
    │   └── assets/
    │       ├── shared-icon.svg
    │       └── README.md
    ├── test/
    │   └── my-new-node/
    │       └── index.spec.js
    ├── README.md
    ├── package.json
    └── .gitignore

./package.json

{
  "name": "my-new-node",
  "version": "0.0.0",
  "description": "",
  "scripts": {
    "prepare": "husky install"
  },
  "keywords": [
    "node-red"
  ],
  "engines": {
    "node": ">=18"
  },
  "node-red": {
    "version": ">=3.0.0",
    "nodes": {
      "my-new-node": "./nodes/my-new-node/index.js"
    }
  },
  "author": "Allan Oricil",
  "license": "ISC",
  "dependencies": {
    "timsort": "^0.3.0"
  },
  "devDependencies": {
    "@commitlint/cli": "^17.7.2",
    "@commitlint/config-conventional": "^17.7.0",
    "husky": "^8.0.0",
    "lint-staged": "^14.0.1",
    "prettier": "^3.0.3"
  },
  "lint-staged": {
    "**/*.{js,jsx,ts,tsx,html,css,json}": [
      "yarn prettier --write"
    ]
  }
}

./nodes/my-new-node/index.js

module.exports = function (RED) {
  const timsort = require("my-new-node");

  function MyNewNode(config) {
    RED.nodes.createNode(this, config);

    const node = this;
    //TODO: create node definition

  }

  RED.nodes.registerType("my-new-node", MyNewNode);
};

./nodes/my-new-node/index.html

<script type="text/javascript">
	<!-- TODO: configure your node -->
	RED.nodes.registerType("timsort", {
		category: "sequence",
		color: "#e2d86e",
		defaults: {},
		inputs: 1,
		outputs: 1,
		icon: "sort.svg",
		label: "timsort",
	});
</script>

<script type="text/html" data-template-name="my-new-node">
	<!-- TODO: configure form -->
  	<div class="form-row"></div>
</script>

<script type="text/html" data-help-name="my-new-node">
	<!-- TODO: configure help description -->
	<p>
		my new amazing node
	</p>
</script>

./.gitignore

node_modules
*.lock

./.husky has the common husky hooks for running commitlint, lint-staged, and tests before commiting
./test/my-new-node/index.spec.js has a pre defined code scaffold for writting test specs for the node
./examples is used to store examples using this node
./nodes/assets is used for sharing assets across multiple nodes
./nodes/my-new-node/assets is used for storing assets that belong to a single node

[AllanOricil]

this tool could even scaffold collections:

[AllanOricil]

What are you thoughts on this @sammachin @knolleary

[AllanOricil]

Another idea is to use yo like verdaccio does

https://verdaccio.org/docs/plugin-generator

[sammachin]

My Thoughts:

In general this seems like a good idea, having tooling to help with developing better quality package;

I think this should be a part of the node-red-dev-cli that we started with the scorecard, there's already a function for validate to run the scorecard so having new functions to create package and add node etc would be a logical extension.
That leads me on to one point here, a package can and often does contain multiple nodes so this needs to cater for that from day 1, we don't want to encourage people to create multiple packages each with a single node when there is a logical grouping.

Looking at the proposed structure I think things could be simplified a fair bit, while we want to encourage people to have well structured code we don't want to overburden them with folders and tools:
husky - This is totally optional and a personal preference from what I can see so shouldn't be in the tool
examples - yes good, not sure why it would need a readme though? 99% of them would be left blank
nodes- yes a single nodes folder seems sensible although I'm not sure why each node then needs it own folder, I tend to just go with separate html & js files for each node but all in the one folder, if custom icons are used (in the node creation then create that folder)
assets - again I'm not sure this is needed on the majority of nodes, this tool should be creating a simple scaffold tht you can build out from in your IDE.
tests - yes a good thing but again the vast majority of packages don't have them today, maybe optional?
README, package.json and .gitignore all good

On the package.json contents again I think this could be stripped back, just adding the node-red bits along with the engines to what npm init does seems like the basics, on the engines front we should ask the developer what they want with a default option of the minimum supported by the current node-red release,
same for node-red version, should default to the minimum of the current maintenance version ??? Or should we default to 1.0.0 @knolleary ?

I think the real value in the tool though would come from speeding up the creation of actual nodes with boilerplate, otherwise this is really just a skeleton package which could be done with a static GitHub repo people just fork.
once the initial package has been created without any nodes then the dev should be able to run another command to add-node, This should then prompt them for some of the node settings, one of the real wins IMO would be to guide them through adding properties to each node and then make it fast to use typed-inputs, these are super useful and IMO give the best user expereience with nodes but are really quite tedious to create, being able to say I want a property of foo, then yes its a typed input and select the types (string, num, json, msg, flow, global, env, jsonATA etc) and having that create all the relevant HTML and set it up in the js would be great.
Also scaffolding out the node help text with each input would be useful.
Similarly some sort of guide for multiple output nodes that sets up the relevant parts of node.send etc would be nice.

I don't think there's any value in adding flows or collections to this tool, this should be about developing packages FOR node-red not about building flows WITH node-red, they are usually very different groups of users and ways of working.

Just to summarise then the workflow for creating a new package with node-red-dev should be something like.

node-red-dev create This asks you a few relevant questions like name, license, etc and sets up the basic structure in a new folder in the current path, very similar to npm init Once done it returns you to a prompt inside that folder
node-red-dev addnode this asks you questions and guides you through creating a node with the chosen properties, outputs etc and then adds the files to the package (should also account for config nodes somehow)
you can repeat addnode as many times as you like to create each node in the package or even come back later and add another node
Once you've then edited the code for your nodes and are happy with how they run you run node-red-dev validate to check the scorecard report on the package before going through the current publishing process (npm publish then the flow library etc)

[AllanOricil]

That is fine to me.
Why are node red admin and dev cli separated? What are the arguments for not having a single node-red bin?

[AllanOricil]

Also, can we please remove -cli from the command and follow Salesforce cli guidelines. I want to simply type:

sfdx and heroku Clis use the following pattern for commands:

{bin name}} {{resource}} {{action}}

Every command follows a pattern so that developers can remember them easily without much mental effort. The result would be:

• node-red node create
• node-red node add

[AllanOricil]

Later we can fuse (pum intended) node-red-admin to node-red

[knolleary]

node-red-admin is already bundled with node-red

node-red admin ....

We chose to keep the Dev took separate as it is for a much smaller audience and we want to be mindful of not inflating the Node-RED base install.

Worth highlighting there is also `https://github.com/node-red/node-red-nodegen which serves a similar purpose but from a different starting point.

[AllanOricil]

Ok, now it makes sense to me. But I want to insist in removing the -cli from the bin name. I don't like it, i have to type more and I don't want to be forced to create an alias after installing it

[sammachin]

node-red-admin is used for managing installations of Node-RED, where the users want to build a flow out of nodes. node-red-dev is for people that want to develop nodes for Node-RED. The first group is much larger than the second group of people.

…

On Sat, 7 Oct 2023, at 12:40, Allan Oricil wrote: That is fine to me. Why are node red admin and dev cli separated? What are the arguments for not having a single `node-red` bin? — Reply to this email directly, view it on GitHub <#86 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABNZ7JOZU5ZGKKZ4GGKGGTX6E5URAVCNFSM6AAAAAA5S7ZTNWVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM3TEMJWHEYDK>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[AllanOricil]

As for pre defined dev dependencies, I'm fine not having them as default, but I insist making them available for a dev to opt-in when running node-red-dev create. These are the ones I usually have in node js projects:

• husky
• eslint
• prettier
• commitlint
• lint-stage

[AllanOricil]

A folder for each node inside /nodes is a pattern that works for 1 or many. A single pattern that fits all is better because removes mental effort. The idea to have a folder for each node is like the way we do when developing lambda functions. We create a folder for each function. Why? Because I project with multiple lamdas can share code/modules which we can then use a bundler to create the dist for each lambda. I would also like to standardize nodes to be created and pass through a bundler, if needed so that the source code can by as DRY as possible.

[sammachin]

The command is `node-red-dev` -cli is just the repo name. Try using it.

…

On Sat, 7 Oct 2023, at 15:16, Allan Oricil wrote: Ok, now it makes sense to me. But I want to insist in removing the `-cli` from the bin name. I don't like it, i have to type more and I don't want to be forced to create an alias after installing it — Reply to this email directly, view it on GitHub <#86 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABNZ7OMCWOCIHCAVUDMD4LX6FP2FAVCNFSM6AAAAAA5S7ZTNWVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM3TEMJXGU4DA>. You are receiving this because you were mentioned.Message ID: ***@***.***>