Custom Module Dev - docs misleading (on Windows?)

Questions
1

Hi there,

I have successfully developed some custom Nodes following the docs by cloning the main n8n repo and directly working into the n8n/packages/nodes-base. So Nodes and creds work just fine.

Then I tried to move this code to a custom module. And this experience was tremendously frustrating. As written in the topic, I am on Windows which sadly (not ment as an accusation) seems to be an issue around n8n.
I was unable to get my custom module into my local n8n installation. Let me describe my journey. This might be helpful to understand where the docs and the dev experience need to be polished:

  1. Came across the “CLI” Page as the only source of creating own nodes outside of the main n8n repo: Using the Node Dev CLI | Docs
    As the page is labelled “Using the Node Dev CLI” I assumed, that all the sections on that page are related to the CLI usage described in “Create the first basic node”. Thus: Deploying a custom n8n-nodes module requires the CLI.
  2. Tried out the n8n-node-dev new CLI and it left me with just one Node file. Creds => One cred file. Then tried n8n-node-dev build seeing it fail on Windows (Posted this with a possible fix here: Not able to create custom node (error TS18003) - #10 by JanTh )
  3. After fixing the n8n-node-dev build I run that again. The files were copied to my Users Home dir → .n8n/custom. But neither the Node nor the Creds appeared in n8n…
  4. Then I moved on to “Create own custom n8n-nodes-module” in the docs. I did not really get what this has to do with the CLI as there is no CLI relation in any way. So I assumed, I have to run the CLI command in the sample Project from github. Cloned the repo and executed n8n-node-dev build in there.
  5. Didn’t work. The CLI requires that there are no directories due to the hardcoded tsconfig-build.json. But the GitHub project is structured with folders - which is a good thing ;-). This doesn’t make sense in the CLI context.
  6. Following the guide using npm link in the Custom project as well as in the n8n ROOT folder. Let me quote the docs:

Then in the folder in which n8n is installed:

# "Install" the above locally published module
npm link n8n-nodes-my-custom-nodes

# Start n8n
n8n

This does not work either. The custom nodes and creds are not included into the n8n instance in any way.

After some time, questioning myself, my coding skills, my reading skills and considering finally going to bed as it might just be too late, I found this side mention from August 2020:

This actually is the issue at hand… You have to call npm link <n8n-nodes-custom> NOT within the n8n root folder but in n8n/packages/cli

Did so and now the Custom Node + Creds are there in my local N8N setup.

Takeaways and suggestions from the past hours driving me mad:

  1. The documentation around Custom N8N Node Modules really needs some overhaul. It is highly frustrating and misleading. At least for Windows Users. Don’t know if it really works this way on Unix / Mac. But as there are issues reported from around 2020 this really should have been fixed / addressed by now :-/
  2. You really should split the Custom Modules Content from the CLI Stuff. I do not see any relation between these two. But the current structure forces one into thinking there is a relation and Modules = CLI. Which obviously isn’t.
  3. The local dev Workflow for n8n modules should be tested and fixed in the docs. At least on Windows, the custom modules have to be linked into the CLI package. This should be either fixed by allowing to link at the top level of n8n as written in the docs or changed in the docs according to the reality :wink:
  4. Update the Starter Repositories Dependencies to match n8n

Hope this helps and still contains constructive and usable feedback between a fair amount of frustration.

Have a great night!

2

I just saw, that someone even already opened a PR to Update the Starter Project :wink:

3

A completely agree that the docs around custom nodes need improvements.

Don’t know if it really works this way on Unix / Mac. But as there are issues reported from around 2020 this really should have been fixed / addressed by now :-/

Keep in mind that we were a small team with many tasks until a couple of months ago - Some will say we are still a small team. With that in mind, we need to make sure that our resources are appropriately used. Improvements in the docs and the CLI around custom nodes are not high in our list of priorities. This, of course, does not mean that we do not know we need to improve them. We are well aware of it. Some new hires have been joining the team recently, and more are to come. That might help to improve the situation. However, I cannot promise anything since this is not my call to make.

Yes, that makes sense.

The difference between Create the first basic node and Create own custom n8n-nodes-module is that the latter can use external dependencies. That is why it has to be an npm package. I would assume that most people will use the Create own custom n8n-nodes-module route.

Agree. This goes back to my first reply.

It does. We rely heavily on our community to test/improve the product.

Let me know if you have further questions.

1 Like