Uibuilder documentation suggestions and improvements


This is going to be a silly question (appologies in advance - and thank you for your time) ......... When I add libraries through the libraries tab of 'edit uibuilder node' none of them are downloaded into /uibuilder/vendor/.... They are downloaded into /uibuilder/node-modules....

and uibuilder.iife.min.js doesn't exist in /uibuilder

I have a feeling there is something I have not read...... I applogise in advance.


Yup! :wink:

So this is the difference between a web server URI and the physical folder layout. The two are actually completely independent in concept.

I refer to the uibuilder FOLDER as the uibRoot folder (you may often see <uibRoot> in the docs to indicate that it can be variable). While normally it exists at ~/.node-red/uibuilder/, it can actually be changed to anything.

When you use the uibuilder library manager, you are actually using the npm utility to install npm modules into uibRoot and so they end up in ~/.node-red/uibuilder/node_modules/.

The 2nd part of the library manager "mounts" the ~/.node-red/uibuilder/node_modules/modulename/ folder to a specific uri, namely ../uibuilder/vendor/modulename/.

BTW, the leading .. simply tells your browser to use the "root" uri of the web address and port that the index.html file loaded from. So, by default, if you are using http://localhost:1880/ as the root http URI and you have named your uibuilder node uibtest, your web root URL will be http://localhost:1880/uibtest/index.html (the index.html part is the default handled by the ExpressJS web server and by default is not shown in the browser). To make life a bit more confusing, Node-RED also lets you set an extra httpNodeRoot which might add some extra URI. e.g. set httpNodeRoot to some-extra-root in settings.js then the example above becomes http://localhost:1880/some-extra-root/uibtest/index.html. This is why I recommend using the leading .. - it makes your URL's a lot more robust in case you need to make changes to the name, port or root URI. In terms of using with Caddy, just make sure that you stay consistent.

Phew, this stuff is hard to explain! Hope that makes some sense anyway.

To recap:

Filing System Folder                       Maps to the URI
~/.node-red/uibuilder/node_modules/            http://localhost:1880/uibuilder/vendor/
                                          AKA: ../uibuilder/vendor/

~/.node-red/uibuilder/uibtest/src/index.html   http://localhost:1880/uibtest/
                                          AKA: ./

Hope that makes some kind of sense? So maybe not such a silly question. It all comes down to how web servers work by the way, not really that much to do with the way that uibuilder does things.

Nope, this one is even more arcane. Again it comes down to how web servers work. They really don't care where things actually live compared to how they are served.

The client library files exist in the front-end folder inside the uibuilder npm module. That whole folder is actually mounted to the ../uibuilder URI. So that the js files and the css files can all be loaded from that URI - e.g. http://red.localhost:3001/uibuilder/uib-brand.css.

Just to make life more confusing though, the ../uibuilder/ URI was a later addition to uibuilder than some of the other ones which is why the same files also get mounted to ./ (e.g. ./uib-brand.css). I realised rather too late that this was not only confusing but might also lead to unnecessary name clashes. The ExpressJS web server is perfectly capable of mounting multiple filing system folders to the same URI's. This is used in a couple of places in uibuilder.

Incidentally, the v6.1 release will have the templates in a far more consistent state with all of this which should hopefully reduce future confusion. In the future, all of the central uibuilder resources will be mounted to ../uibuilder/ and will be referenced as such in the templates and examples.

Yes, the Tech Docs. :grin:

But also, there are two extra documentation links beyond the tech docs that are accessible in a uibuilder node's Editor config panel.


The "uibuilder details" page and the "Instance Details" page. These can be rather confusing web pages but are worth reading through a few times. The "uibuilder details" page in particular shows you all of the gory details about the inner workings and configuration of uibuilder.

Possibly the most important part being:

a table that shows you all of the installed libraries along with both the URI (browser entry point) and the filing system folder. The entry point is an estimate based on the library author's package.json and so is not always correct - but is a useful starting point. You will see some of this data now in the library tab itself.

Then further down that page, you will see "uibuilder ExpressJS Routes" - this section attempts to detail ALL of the URI's (path) that uibuilder mounts along with, where possible, their filing system locations (folder). And a brief description of what the URI is for. Some of the terminology can be confusing though - but if you are interested, have a look on the ExpressJS website to find out what "router" and other terms mean.

Here is an example for a uibuilder node that has the URL set to "home":

You can see that several routes are mounted to the same path (URI).

No need, as with any open source (and most closed source) apps, the documentation is an ongoing work. And as you can see, some of the concepts are not especially easy to explain!

The tech docs do get a bit of TLC from time-to-time and they are slowly improving. v6.1 will improve them again now that the new client libraries are the standard and we are increasing the number of nodes that come with uibuilder.

Do keep the questions coming. No such thing as a stupid question - plenty of stupid answers though! :grin:

I always attempt to learn from these questions and think about how the documentation might be improved.

I'm also always open to feedback and suggestions both for the documentation and videos.

I'm also always open to feedback and suggestions both for the documentation and videos.

Pardon my intrusion

I have taken an occasional glimpse at the documentation, but to be frank it is quite daunting and confusing.

The docs open with statements about version this version that.

(New) users are not interesting in stories about what was and what will be. People just want to click and go - reading time is at a premium.

I often see your responses about v6.2, 6.1, 5.something is it all really relevant to get people going ? (You probably think 'yes', that is not the point). This is context that you are familiar with but new people are not.

The first line states "uibuilder is a low-code solution for easily building data-driven web sites"

But going through the documentation, it is pages and pages of text without a beginning, nor end - is it then really that simple ? (ie, why would providing a single simple flow not suffice ?)

It goes on about uibuilder.iife.js, uibuilder.esm.js, uibuilderfe.js what is this, why not give something that works (I am not arguing against it, I am giving an outsider perspective).

In the beginning of uibuilder I have tried it out but was in need of simple examples (which I provided) as it goes all over the place.
Code examples that are filled with comments, unnecessary "syntax highlighting" functions that make it really hard to weed through.

I know and understand there is a lot of passion in the project, but I think it may help to look at with a helicopter view or use an ELI5 approach, because you cannot and don't have to explain every browser/node/javascript exception/intricacies that exists, it takes away from the primary focus.

I think for me the most confusing is the intertwining of versions and referenced libraries througout each page in the documentation (NOTE, Attention, NOTE). If you are able to separate this information, it may become more clear. Like, if you reference the "esm" vs "iife" etc with their own caveats/exceptions.

My feedback would be - keep the documentation focussed: how to define a new endpoint, how to send/receive/display/cache/replay data, it will explain a lot, the rest is nice to have and/or people will figure it out themselves. When a user wants to use react/vue they know probably already know more than you can cover.

1 Like

Hi bakman2,

Many thanks for your feedback and I certainly acknowledge its veracity. :grin:

You are right and while not wishing to offer excuses, it is because the documentation has evolved more than it was designed. Especially the Tech Docs which really are now just "The Docs". This was an evolution from a combination of the WIKI and the node's help panel. Originally was designed just for detailed technical documentation but has now evolved into general documentation.

I am indeed trying in each release - as time permits (a major issue of course) - to simplify and separate out the overview from the detail and your feedback on that is excellent. Indeed, this is why I keep asking for feedback in almost all of my posts about uibuilder. Unfortunately, only very few people ever give any so I plod on in my own little world which is far too close to the detail.

I'll take this to heart and continue to work on improving the docs. The README as well needs a serious trim now that the tech docs are so comprehensive.

:sigh: I wish that were so. Unfortunately, it often isn't. And I'm so close to it all that it is hard for me to see why it seems hard to people. Add a node, give it a url, deploy, add output debug nodes, send a msg. Done!

But there is a starter page for getting going (though from your comments, it probably needs thinning out) and an introductory video now.

Ah, an occupational hazard unfortunately. I'm an IT Enterprise Architect by trade. :grin: But really good point, I need to better structure the information and move the details down or out.

This is one of the things that has dramatically changed over the years uibuilder has been around. Vue with bootstrap-vue was originally a must for beginners since it made creating a nice UI so much easier. But that is no longer the case since uibuilder, HTML and browsers have moved on so much. So you will be glad to hear that in v6.2, the "blank" template really will be blank. With other templates and example flows providing more complete starting points for people wanting Vue, Svelte, etc.

So yes, that whole area needs to be simplified in the docs.

Thanks again for the great feedback. Keep it coming!

1 Like

You might be interested to see my proposed new README file for uibuilder. Greatly tidied up.
@bakman2, is that closer to what you were referring to?

node-red-contrib-uibuilder/README.md at v6.1.0 · TotallyInformation/node-red-contrib-uibuilder (github.com)

Just spotted an error in the "Future direction" section that I need to correct. and fixed.

Looks much cleaner to me. I would also move the two parts about dev version and old version to a separate section later on. And remove the para about semantic versioning - just have the changelog.

1 Like


On the subject of documentation I wonder if it could be made easier for those coming from other web production tools. For example I spent months last year producing a home automation website in Django. Then I discovered NodeRed and Mqtt, which co-ordinates all my tech in a more intuitive (code-less) way and does most of the 'heavy lifting’. …… Hence why I want to re-develop my website in UIBuilder.

I don't readily see from the documents how to....

make my own inherited css files and use to us a jpg as a background to a webpage
use bootstrap generally (I’m assume no different)
have multiple webpages and navigate between them
have webpages inherit from a base page
where to store some of my static e.g. the background jpg file

I think most of this is about ‘location’

include plotly graphs
include cctv streams

To be clear I have only spent 1/2 an hour reading the docs and I have not searched this forum for answers. I don’t expect to be ‘spoon fed’, but some signposts would be helpful

You and your volunteers have done a great job though, huge amount of work !!!

Thank you


Well, I don't really want to go too far down the how to do web development rabbit hole to be honest. There is enough to do as it is and keeping up with the docs is hard work. I think that some of the following might be useful on the WIKI though? And that is open to all to edit. :wink:

But lets see what might be generally useful for the docs ... please don't take my responses here as a criticism by the way, I genuinely want to understand the answers so that I work out what is best to do.

  • make my own inherited css files and use to us a jpg as a background to a webpage

    Isn't this standard web development? I do state several times that uibuilder lets you use standard web development workflows and tools - maybe I need to emphasise that?

    I might create a video at some point about web development workflows though. I suspect that would be useful. Added to my list.

    Oh, and I need to explain the common folder better, I think it currently gets lost in the noise. It is the location you can put things where they will be available to all uibuilder instances on a standard URI.

    Of course, you can also use Node-RED's static folder too if you want.

  • use bootstrap generally (I’m assume no different)

    I don't think that will ever make it into the uibuilder docs but I'd be happy if someone contributed to the WIKI. I don't use bootstrap so I can't really help.

  • have multiple webpages and navigate between them

    This one is fair, at least the multi-page part and should be included somewhere - adding it to my tutorial list. I spend too long developing uibuilder and not enough developing web apps!

    Inter-page navigation is standard web stuff, people do need to learn some things for themselves. :rofl:

    But Single-page app virtual page routing is on the list. I think there is a WIKI article on doing it with Vue but I'd like eventually to come up with a vanilla HTML way.

  • have webpages inherit from a base page

    Do you mean some kind of templating? Yes, this is something that needs covering. If only because there are several options ranging from server-side templating, zero-code (using the uib-element node from v6.1.

    In addition, some further options will become available in v6.2

    Also, the zero- and low-code options let you build HTML that you can then save and reuse. That will be possible all in Node-RED from v6.2. At present you can do it via your browser of course.

    uibuilder lets you insert/remove/update HTML dynamically direct from Node-RED so traditional templating isn't always needed. Still working out all of the possibilities this gives so documentation a little light on the ground as yet.

  • where to store some of my static e.g. the background jpg file

    Interesting. That tells me that you've not quite grasped the folders that a uibuilder node creates and mounts for you. Since the whole idea behind uibuilder is the fact that it uses the servers filing system to present static files via http.

    So clearly we need to find better ways to get that concept across better.

    The answer, by the way, is to put it in the same place as your index.html (or a sub-folder) since that folder becomes the root URI that is served up.

Yes, and even I find that the concept of how a web server maps (mounts?) filing system locations to virtual URI's fairly complex and even harder to explain.

That probably needs its own page in the docs then as well as a complementary video on the subject.

Don't forget the WIKI :wink: - and the Node-RED flows site - and the built-in example flows! To say nothing of my (so far single) "official" YouTube playlist and other people's uibuilder-related content.

I think the new README may help expose those better.

No, that's fine. This is exactly what I need to be able to improve things. Early impressions are important and beginner impressions help drive better introductory documentation.

One thing I really need to do is a video on how to spell uibuilder! :rofl:

Hint: all lower-case, no spaces or dashes or underscores.

More seriously, I'm generally knocking around the forum if you need some answers - just ask.

Note that I split this conversation from its original home

Here is a list I've come up with so far of subject areas that need unpacking. They may get their own pages in the docs and will hopefully get videos at some point.

In no particular order. Feel free to vote up specific ones :slight_smile:

Using the Example flows

Simple, dynamic UI

Caching data



Development workflows

Multi-page development & inter-page navigation.

SPA routing

Options for templating/inheriting from a base page

Static files, shared files, common folder

Converting data into a web page (zero-code/low-code/saving)

Middleware (Express and 2xSocket.IO)

Instance API's

"....... please don't take my responses here as a criticism...." I don't. You have been kind and exceptionally patient. Thank you.

Although I have developed my own Django based website running in dockers using Django, Celery, NGINX, REDIS, Channels, reading sensors, controlling hardware .....blah blah balh I am no expert. I only learned enough of each to do what I wanted to do. I am no website developer so some of the stuff I should know…. I don’t :slight_smile:

but I am prepared to do the research and learn. Your answers are useful signposts as usual. I remain keen to get my website up and running in ‘uibulder’….. spelt correctly…… tee hee… and if I can help others along the way then so much the better.


1 Like

I forked your repo and rewritten the readme. This is the approach I would take.

The statement:

It includes many helper features that can reduce or eliminate the need to write code for building data-driven web apps.

I tried to link to these "helper features", but I could not actually find them in the documentation, so as a user I would be lost.

1 Like

Some useful simplifications, I will incorporate some of them, thanks.

Good point. But I didn't want to go down that rabbit hole in the readme and I'm trying to keep that fairly simple. Clearly though, I need something that I can link to that further signposts to those capabilities. That would also be true for the more detailed "Features" section which is now behind details tags so you don't have to wade through them unless you want to. Lots more links needed.

All added to the roadmap for future updates.

I'm aware that I need to go through a similar process of rationalisation for the full documentation so that everything is more consistent and discoverable. Of course, this is quite a large job in itself so it is likely to get done over time.

If you were to dig into the docs folder for the v6.1.0 branch, you will already see placeholders for each of the nodes. This is new because originally of course, we only had 1 node! Not much in there as yet because I need to re-organise things further.

I've pushed the updated readme to the v6.1 branch. I think it looks much better already. Thanks for all the input so far. It doesn't loose the features detail though but rather hides it since I didn't want to cut everything out since the readme is also the front page for both the Flows entry and the npmjs.org entry.

node-red-contrib-uibuilder/README.md at v6.1.0 · TotallyInformation/node-red-contrib-uibuilder (github.com)

Writing is hard. Documentation is hard.
Writing good documentation is next level.

It is tough and consumes a lot of energy to paint a clear picture that can (hopefully) get the message across. I am (professionally) very familiar with this fact.

With uibuilder it may be even harder because of its flexibility.

Still, I would recommend to focus on your own project, because it can read like an internal struggle against other available options:

uibuilder is rather the opposite of Node-RED's Dashboard. Whereas Dashboard is designed to make it very easy to create a UI but trades that off with some limitations, uibuilder is designed to let you do anything you can think of with any framework (or none) but at the trade off of having to create more of the page structure yourself.

It is not relevant is it ? It is distracting to me as a potential user: "hmm what is this ? dashboard ? Oh let me look at dashboard".

A data-driven web page/web app utility for Node-RED.

This does not describe what it actually does as a consequence when you install it (this is why I rephrased it - keep focus and explain the purpose).

Just my 2 cents - and a side note: don't be afraid to delete information/pages.

An interesting point, thanks. Maybe it is time for uibuilder to grow up! When I started, Dashboard was it - that or manual http-in/-out. So explaining the reasoning for having uibuilder was important. But perhaps you are right and uibuilder stands on its own now and doesn't need to apologise for not providing what Dashboard does. :grin:

Sorry, I now have to admit that I actually missed that part!

I don't want to completely lose the "data-driven" part because that is one of the things makes uibuilder stand out from other tools. It is the data integration between node-red and the browser that is important. Without that, you've just got another way to manage web pages and there are tons of those.

However, the point about stressing the webserver aspect is food for thought. I suppose I've shied away from saying that because I believe that it is Node-RED that provides the web server, uibuilder consumes it. But as I re-read your text, I rather like it. I'll give it a bit more thought but that may well become the first para.

And a very valuable 2 cents they are! Many thanks again for the engagement and suggestions.

:rofl: Hey, I'm an IT Architect and designer - information is my life!! Deleting information is like cutting off my own leg. :scream:

I think that we've got the README into a better balance anyway. Doubtless more tweaks in the future but enough for now and it gives me some better guidelines for changes to the rest of the documentation. A very valuable exercise.

Maybe the tag line for the next release should be something like "Graduation Day" :wink:

As I mentioned to someone else in here recently, sometimes we can go a 'bit' too far with things.

Unfortunately, we, as the Architects know the ins and outs of an item and we forget that too much information doesn't help, just as much as too little information!

Writing a good useful Technical Document is difficult, especially if you have an audience that isn't that technical.

I have started looking at 6.1.0 today, I think I have a question for you tomorrow! Just need to exhaust all options first!!

Keep up the good work, I will read Docs in parallel with doing and try to help (as a less technical user).

1 Like

Great, have fun. Happy to answer questions as always.

Thanks :grin:

Always useful. Just bear in mind that I know that some of the docs are pretty bad - output from a fevered mind :rofl:

It would be helpful to oldens like myself if in the Using the List node you specifically state

(instead of It uses the new configuration-driven UI capabilities of the new client library (it doesn't work with the old uibuilderfe.js client)

use the template No framework, modern ESM client.

I had read the notice in the setup for the list node but it took me ages to twig that maybe I should try another template (I was still with the default Blank Template)

1 Like