Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including node-red-contrib-uibuilder with all npm packages installed. Try it out:

var nodeRedContribUibuilder = require("node-red-contrib-uibuilder")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

node-red-contrib-uibuilder v1.2.6

Easily create web UI's for Node-RED using any (or no) front-end library. JQuery and normalize.css included by default but change as desired.

NPM Version NPM Total Downloads NPM Downloads per month GitHub last commit GitHub stars GitHub watchers GitHub license Min Node Version Package Quality Dependencies Open Issues Closed Issues

1. node-red-contrib-uibuilder

A Node-RED web user interface builder. UIbuilder Aims to Provide an easy to use way to create dynamic web interfaces using any (or no) front end libraries for convenience.

The key features and benefits are:

  • Designed as an alternative to the Node-RED official Dashboard.
  • Have as many custom user interfaces as you want. Just 1 node is needed for each entry point. Use link nodes to send data from other parts of your flows.
  • Has a control interface separate to the message interface. Know when a browser connects or disconnects, send cached data.
  • Much lighter in weight and more mobile friendly than the Node-RED official Dashboard (assuming you don't use Angular as your framework).
  • Use any front-end framework you like. Tested with at least JQuery, VueJS, MoonJS, REACT, UmbrellaJS and Riot.
  • Use without any front-end framework if you like. Keep it light and simple.
  • The included front-end library provides connectivity to Node-RED and msg event handling.
  • Write your own HTML, CSS and JavaScript to define the perfect front-end user interface for your needs.
  • Needs almost no boilerplate in your front-end code in order to work.
  • Simple included example works out-of-the-box, no need to install anything other than the node.
  • MoonJS extended and caching example flows included.
  • Edit your front-end code (index.html|js|css, etc) directly in the Node-RED admin ui. No need for filing system access to the server any more.

Current limitations are:

  • You have to write your own HTML, uibuilder doesn't (yet) do it for you. This is by design. I hope to have a component design available at some point which will give additional options and make the UI building easier.
  • You have to remember to install any front-end libraries (e.g. Vue). Except for JQuery that Node-RED installs anyway. I will be providing an installer in another release soon.
  • You have to know the front-end library locations for installed libraries and edit your HTML accordingly. I hope to add known libraries at some point so that the admin UI will give you the correct entry points.
  • You cannot (yet) compile/compress your custom front-end code (HMTL, JS, SCSS, etc.) for efficiency. This will be added soon.

This is rather the opposite of Node-RED's Dashboard. Whereas that is designed to make it very easy to create a UI but trades that off with some limitations, this is designed to let you do anything you can think of with any framework but at the trade off of having to write your own front-end code. This node should also be a lot faster and more resource efficient in use than Dashboard though that obviously depends on what front-end libraries and frameworks you choose to use.

1.1. Contents

1.2. Additional Documentation

There is more information available in the WIKI.

1.3. Out of the box

Out of the box, you get a simple index.html template with matching index.css & index.js JavaScript. These are automatically copied over from the module's master template folder to the instance's src folder when you first deploy so that you can override them. If you want to reset them, you can simply delete your local copies and the master templates will be copied back when you restart Node-RED (this can be turned off with a flag).

JQuery is used in the default JavaScript to give dynamic updates to the web page. If all you need to do is some simple dynamic updates of the page, JQuery is likely enough. Normalize.css is also provided to help you with standard look and feel. Just remove the references in index.html and the code from index.js if you don't want them.

Any msg sent to the node is forwarded directly to the front-end and is available in the global msg variable as it would be in Node-RED, use the msgSend function to send a message back to Node-RED that will be passed downstream from the node.

The msg can contain script and style information that will be dynamically added to the web page if allowed by the settings.

You will want to change the front-end code to match your requirements since, by default, it displays some rough dynamic information using JQuery and reflects any received messages back to Node-RED (including control messages). You can find this in ~/.node-red/uibuilder/<url> by default. As a minimum, you need an index.html file. But you need the index.js (or some equivalent) file as well if you want to do anything useful. You will also want manifest.json and/or uibuilder.appcache for mobile use.

The local index.(html|js) files are well documented and should show you how to get started with your own customisations. There are also some examples, with code, on the WIKI.

The node also has a second output port. This is used exclusively for control messages. Control messages are sent by the server when a client connects or disconnects and by the front-end client when the websocket has connected and when the client is ready to receive messages (after window.load by default). The connect and ready messages have a "cacheControl": "REPLAY" property which is designed to be used with node-red-contrib-infocache or your own message cache (example) so that new or reconnecting clients can receive cached information (similar to Dashboard widgets).

Editing your html, js and other front-end files is often best done using a proper code editor such as Microsoft's Visual Studio Code, ATOM or similar. However, that requires access to the server's filing system which can sometimes be an issue. As of v1.1, uibuilder now has the ability to edit any text-based file in the src folder right from within the Node-RED admin UI. It uses the excellent ACE editor to do that just like other nodes.

back to top

1.4. Features

  • A single node is used to define an end-point (by its URL path). The node can be included in flows as many times as you like - but each instance must have a unique URL path name.

  • Each node instance gets its own Socket.IO namespace matching the URL path setting. Note that Socket.IO will efficiently share sockets while keeping traffic separated by namespace.

  • There is a front-end library uibuilderfe.min.js or uibuilderfe.js that hides all the complexities of using Socket.IO so that your own FE code is easy to write. It provides a simple event handling system so that you can subscribe to changes and process them as they happen. The default index.js file has details and examples of use.

  • Users can install front-end libraries using npm into their userDir folder. If using the src sub-folder, these can be accessed in front-end code via the "vendor" path, see below. The list of user libraries made available is given via Node-RED's settings.js file in uibuilder.userVendorPackages (Eventually, also via the nodes settings).

  • The node's module contains default html, JavaScript and CSS master template files that are copied to your local src folder for you to edit as required.

  • Any msg sent to a node instance is sent through to the UI via Socket.IO. If topic is set in settings and not in the msg, the version from settings will be added. NOTE that this may present security and/or performance issues. In particular, you should remove msg.res and msg.req objects as they are both very large and often contain circular references.

  • Sent msg's can have a msg.script and property that will dynamically add that code to the web page - if allowed by the settings (default is off)

  • Including a _socketId attribute on messages sent from Node-RED will send to that ID only. An ID is associated with a specific browser tab and is reset when the page is reloaded so this isn't too easy to use as yet (see To Do list). The _socketId attribute is added to any msg sent from the client to Node-RED. See the WIKI for more information.

  • A second output port gives access to some control messages. This allows additional processing when a client connects or disconnects, an instance is (re)deployed or there is a socket error. You could, for example, output some standard information when a new client connects. Or you could use the information to keep utilisation metrics. See the Control Message Structure page in the WIKI for details.

  • On deployment of the first instance of uibuilder, a new folder is created within your Node-RED user directory (typically ~/.node-red) with a fixed name of uibuilder.

  • On deployment of any new instance, a new sub-folder within uibuilder is created. The name is the same as the URL path specified in the node instance's settings. (defaults to uibuilder). src and dist sub-folders are also created.

  • If the local dist folder contains an index.html file, the dist folder will be used, otherwise the src folder will be used.

  • Any resource (html, css, js, image, etc) placed within the dist/src sub-folder is available to the browser client. The default URL would be http://localhost:1880/uibuilder (where the path is set as per the point above). That URL will load index.html.

  • You have access to ExpressJS middleware simply by providing a function definition in settings.js. This lets you, for example, have custom authentication/authorisation.

  • Edit your front-end source files directly within the Node-RED admin UI, access to the server's filing system is no longer absolutely necessary.

  • Eventually, a link to webpack will be provided to enable packing/compiling of src code to dist. This will enable front-end code to use non-native libraries such as JSX, ES6, Foundation, etc.

You might like to try some lightweight front-end libraries (in addition to or instead of the included JQuery and Normalize.css):

  • MoonJS is a minimal, blazing fast user interface library. Only 7kb. Based originally on the Vue API, uses a virtual DOM, possibly the simplest UI library to use. You can remove JQuery if you use this, it isn't needed.
  • RiotJS is a lightweight UI library, REACT-like but only 10k.
  • Ractive.js is a template-driven UI library. Very simple to use
  • Mini.CSS is a minimal, responsive, style-agnostic CSS framework. Only 7kb. You can remove Normalize.css if you use this, it is built in.

Or indeed, the heavier-weight classic frameworks such as:

Examples for using some of these are available in the WIKI

back to top

1.5. Known Issues

I don't believe any of the current issues make the node unusable. They are mainly things to be aware of & that I'd like to tidy up at some point.

  • It is common to need to send a number of messages from Node-RED to the front-end, specifically when a new client is loaded or a user refreshes the client browser. This is not catered for natively by this node. You can either handle this manually or use the companion node node-red-contrib-infocache (not yet written I'm afraid). Simply send the control messages to an infocache node (or manual equivalent - see the WIKI) and it will resend all cached messages back to the individual client.

  • Socket.IO isn't secured by default Use Node-RED's security features to secure things properly before considering use over the Internet.

    You could also work around this by using a proxy such as NGINX or HAproxy to be the TLS endpoint. Just make sure you proxy the websocket traffic as well as the standard web traffic.

  • Uniqueness of the URL is not yet being validated for multiple instances, could cause some "interesting" effects! This should be resolved in v1.2 or thereabouts.

  • Modules to be used for front-end code (e.g. JQuery) must be installed under <userDir>. Of course, you can use them direct from an Internet CDN if you like. I plan to include npm install support to enable this in the admin ui after v1.1.

back to top

1.6. Dependencies

See the package.json file, these should all be installed for you. Currently:

  • JQuery - front-end only, remove from your index.HTML if not needed.
  • normalize.css - front-end only. Not needed if using a CSS framework like Bootstrap or Picnic.CSS. Installed by uibuilder.
  • Socket.IO - front-end and server. Installed by uibuilder to ensure a known version (Node-RED installs its own version).
  • serve.static - server only. Installed by uibuilder.
  • winston - server only - for more detailed debug logging if needed. Installed by uibuilder.

Any packages that you define in settings.js must currently be installed by you under your userDir folder prior to use.

1.7. Install

It is now best to install Node-RED nodes using the Node-RED admin interface. Look for the "Manage Palette" menu item. Alternatively, Run the following command in your Node-RED user directory (typically ~/.node-red) npm install --save node-red-contrib-uibuilder.

Run Node-RED and add an instance of the UI Builder node. Set the required URL path and deploy.

The UI should then be available at the chosen path. The default would normally be http://localhost:1880/uibuilder (if default Node-RED and node settings are used).

For information on what to do next, see the Getting Started WIKI page.

back to top

1.8. Node Instance Settings

Each instance of the uibuilder node has the following settings available.

name (optional)

Only used in the Node-RED admin UI.

topic (optional)

Only used if an inbound msg does not contain a topic attribute. Passed on to client UI upon receipt of a msg.

url (required, default = 'uibuilder')

The path used to access the user interface that this node builds. So on localhost, if none of the port nor https nor httpRoot settings are defined (in Node-RED's settings.js file), the URL of the default interface would be http://localhost:1880/uibuilder

It is up to the flow author to ensure that no duplicate names are used, the node does not check or enforce uniqueness.

Forward input to output? (default = false)

Forwards a copy of every received message direct to the output. Adds the topic from the above setting if one isn't present in the msg.

Note that this may result in multiple output messages if your front-end code also auto-sends inbound messages.

debug (optional, default=false)

Only available using the uibuilder.debug attribute of settings.js. Set to true to output additional debugging information.

Allow passing to the front-end

Two flags that allow JavaScript and/or CSS styles to be sent via a msg from Node-RED to the front-end. The code is added to the browser's DOM dynamically.

Warning Obviously, this can be a security problem if you aren't careful so use with care.

userVendorPackages (optional)

A list of npm package names (as they appear in node_modules) that the node will make available to front-end code under the uibuilder/vendor path.

All instances of this node will also use the uibuilder.userVendorPackages attribute of settings.js unless defined in the node's settings.

back to top

1.9. uibuilder settings.js configuration

uibuilder has some global configuration settings available in Node-RED's settings.js file, typically found in userDir (normally ~/.node-red).

Note that you do not have to have this set in settings.js if you are not using any of the entries. Also, none of the properties are required and so can be missed off if you don't need them. The Vendor Package list defaults to an empty array, Debug defaults to false, Middleware entries default to nothing.

    uibuilder: {
        // List of npm modules to be made available to any uibuilder instance.
        //   The modules MUST be manually preinstalled at present. e.g. `npm install slim-js` in ~/.node-red folder.
        userVendorPackages: ['riot', 'moonjs', 'slim-js', 'ractive', 'picnic', 'accounting', 'date-format-lite'],
        // Controls the amount of debug output to ~/.node-red/uibuilder.js
        debug: 'verbose',  // error, warn, info, verbose, debug, silly; true = silly, false = none
        // Provides an ExpressJS middleware hook. This can be used for custom authentication/authorisation
        //   or anything else you like. If NOT provided, uibuilder instances will also check if
        //   httpNodeMiddleware available.
        // @see
        // middleware: function(req,res,next) {
        //     console.log('I am run whenever a web request is made to ANY of the uibuilder instances')
        //     // ... do some user auth checks ...
        //     // if auth checks fail: next(new Error('Authentication error')) otherwise:
        //     next()
        // },
        // Provides a Socket.IO middleware hook. This can be used for custom authentication/authorisation or anything else you like.
        // socketmiddleware: function(socket, next) {
        //     /* Some SIO related info that might be useful in security checks
        //         //console.log('--socket.request.connection.remoteAddress--', socket.request.connection.remoteAddress)
        //         //console.log('--socket.handshake.address--', socket.handshake.address)
        //         //console.dir('-- Sockets connected --', io.sockets.connected)
        //     */
        //     console.log('Socket.IO middleware: I am only run when a client FIRST connects')
        //     console.log('Socket Middleware. ID:',, ' Remote Addr:', socket.conn.remoteAddress)
        //     // ... do some user auth checks ...
        //     // if auth checks fail: next(new Error('Authentication error')) otherwise:
        //     next()
        // },

You can miss any settings out that you don't need.

back to top

1.10. Discussions and suggestions

Use the Dashboard category in the Node-RED Discourse forum or the #uibuilder channel in the Node-RED Slack for general discussion about this node.

Or use the GitHub issues log for raising issues or contributing suggestions and enhancements.

1.11. Contributing

If you would like to contribute to this node, you can contact Totally Information via GitHub or raise a request in the GitHub issues log.

Please refer to the contributing guidelines for more information.

1.12. Developers/Contributors

  • Julian Knight - the designer and main author.
  • Colin Law - many thanks for testing, corrections and pull requests.
  • Steve Rickus - many thanks for testing, corrections and contributed code.
  • Ellie Lee - many thanks for the PR fixing duplicate msgs.

profile for Julian Knight on Stack Exchange, a network of free, community-driven Q&A sites

back to top

1.13. Preference Tree

The uibuilder node adds a number of statically served web resource locations (physical file-system locations) to the URL path (default /uibuilder) defined. It is up to the user to ensure that file/folder names do not clash.

Note that if using the local folders (1 or 2 below), the default/master folders (3/4) are also still available.

The order of preference is as follows:

  1. The dist folder within the node instance URL setting (default: uibuilder, default physical location: ~/.node-red/uibuilder/uibuilder/dist)

    only added if index.html exists in this folder

  2. The src folder within the node instance URL setting (default: uibuilder, default physical location: ~/.node-red/uibuilder/uibuilder/src)

    only added if index.html DOES NOT exist in the dist folder

    In this case, an optional node configuration variable (uibuilder.userVendorPackages) is used to provide a list of package names that will be added to the vendor sub-path of the URL so that users can install their own front-end libraries. This is only added when not using the dist folder as that is expected to have all of the vendor code compiled together using webpack.

    If you want to reset any of the front-end files back to the master template, simply delete one or more of them from this folder. They will be copied back from the master when you restart Node-RED.

  3. The node installations dist folder (default physical location: ~/.node-red/node_modules/node-red-contrib-uibuilder/nodes/dist)

    only added if index.html exists in this folder

  4. The node installations src folder (default physical location: ~/.node-red/node_modules/node-red-contrib-uibuilder/nodes/src)

    only added if index.html DOES NOT exist in the dist folder

    This folder currently only contains am images folder that contains: logo-red.png, logo.png, node-red.ico.

    Override these as needed using the local folders (1/2).

The vendor subpath will be always be available with some pre-installed vendor packages. Currently normalize.css and jquery are always available.

In addition, this node uses the httpNodeMiddleware Node-RED setting allowing for ExpressJS middleware to be used. For example, implementing user security.

back to top

1.13.1. Front-end path summary

Front-end files in ~/.node-red/node_modules/node-red-contrib-uibuilder/nodes/src/ may use the url paths:

  • [/<httpNodeRoot>]/<url>/ - for most things e.g. <script src="index.js"></script>

  • vendor - for things like normalize.css & JQuery and other front-end libraries installed using npm either by this module or as packages in your userDir e.g. <link rel="stylesheet" href="vendor/normalize.css/normalize.css">

  • <script src="/uibuilder/"></script> - for The static /uibuilder prefix is used here to ensure all instances of clients for this node use the same, correct, instance of

1.13.2. Physical file/folder location summary

Folders and files for resources on the device running Node-RED are:

  • <userDir>/uibuilder/<url>/src/ - local source files for front-end use (e.g. html, js, css)
  • <userDir>/uibuilder/<url>/dist/ - local compiled files for front-end use
  • <userDir>/node_modules/node-red-contrib-uibuilder/nodes/template/ - this modules master template source files for front-end use - copied to local folders on deployment
  • <userDir>/node_modules/node-red-contrib-uibuilder/nodes/src/ - this modules source files for front-end use (e.g. html, js, css)
  • <userDir>/node_modules/node-red-contrib-uibuilder/nodes/dist/ - this modules compiled files for front-end use
  • <userDir>/node_modules/<package-name> - when included via the uibuilder.userVendorPackages global setting (in settings.js). Note that each package will have its own folder structure that you will need to understand in order to use the package in the browser. These are often poorly documented.

back to top

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free