noflo-ui: a browser based IDE for FBP flow programming

An IDE that runs in a browser tab

The NoFlo Development Environment is an offline capable, client side web application that helps users build and run flow based programs built with FBP compatible systems such as NoFlo, MsgFlo, imgflo and MicroFlo. The homepage for the project is app.noflojs.org, and the package is published under the MIT license.

Two words in that description carry most of the design. Client side means the whole editor lives in the browser, with the graphs and their state held locally rather than on a server. Offline capable follows from that, and it is the reason the application can be used on a machine with no network, in a workshop, or on a flight.

The graph editor itself comes from a separate project. The README points to the-graph, the graph editor widget used for editing flows, which is a dependency rather than part of this repository.

The history explains some of the shape too. The project was made possible by 1205 Kickstarter backers, and the change log is kept in the repository as CHANGES.md. A tool built by a campaign community for flow based programming tends to grow by accretion, and the architecture section later in the README admits as much, saying that the principles it describes are the architecture the project is aiming towards and that parts of the system are being refactored to fit it as they are modified.

For anyone evaluating the codebase today, that note is the most important line in the document.

The FBP Network Protocol is the real boundary

The design decision that makes the tool useful across projects is that the UI does not talk to NoFlo directly. Even though the UI itself is built with NoFlo, it is not talking directly with NoFlo for running and building graphs. Instead it uses the FBP Network Protocol, which enables it to talk to any compatible FBP system.

The README says over five different runtimes are known to work, and the contract for joining that set is straightforward: implement the protocol in your runtime and you can program it with the NoFlo UI. If you use WebSockets or WebRTC as the transport you do not need to change anything on the NoFlo UI side, and other transports can be added through the separate fbp-protocol-client project.

That is a genuinely good interface decision. The editor is a client of a protocol rather than a front end for one implementation, which means a team writing a runtime in a language of their choice gets a visual editor for free, and a team with an existing runtime can add a protocol adapter rather than a whole editor.

The cost is that the UI is a thin layer over the protocol, so everything the runtime does, including any editor specific affordances, has to be expressible in the protocol. The runtime information files described later are the mechanism for closing that gap.

Live mode: the runtime connection travels in the URL

How a user's browser finds a runtime on the developer's machine is the interesting operational detail, and the answer is a URL.

The easiest way to pass the connection information is the live mode, where the connection details are passed to the app via URL parameters. The README gives the shape of such a link, with the protocol and address encoded into the fragment:

http://app.flowhub.io#runtime/endpoint?protocol%3Dwebsocket%26address%3Dws%3A%2F%2F127.0.0.1%3A3569

Three parameters are supported for the endpoint. The protocol selects the FBP protocol transport to use for the connection, with possible values including websocket, iframe and webrtc. The address is the URL to use for the connection, which can be a ws:// URL for WebSockets or the signaller URL and connection identifier for WebRTC. The secret is the secret to use for communicating with the runtime.

These URLs can be shown on command line output, or provided to the user by another mechanism, and the README links a video demonstration of opening the app in live mode via an NFC tag. That example says a lot about the intended workflow: the developer prints a link, the developer taps a tag, and the browser connects to a runtime on the developer's own machine without any configuration dialog.

The secret parameter deserves attention. It is how the runtime knows whether the browser is allowed to talk to it, and because the whole configuration travels in a URL fragment, it is the piece of the setup to get right when you distribute the link.

Registering a runtime with a YAML file

Beyond the protocol, the UI can carry presentation information for a runtime, and the mechanism for that is deliberately small.

One can optionally add component templates, syntax highlighting and a get started link for new runtimes. The steps are: add a new YAML file with runtime info as ./runtimeinfo/myruntime.yaml, with the msgflo file given as the example; include it in ./runtimeinfo/index.js; commit the changes; and send a pull request so everyone benefits.

The interesting property is that the runtime registration is not code. A YAML file plus one line of an index, submitted as a pull request, is enough to make a runtime appear with its own component palette and syntax highlighting.

For a runtime author that is a very low cost of entry, and for the UI maintainers it keeps the runtime catalogue in the repository rather than in a server side database. The cost is that a runtime shipped outside that pull request process is functionally invisible in the editor, with no palette and no highlighting, even though the protocol connection still works.

Building and running the environment

The README is careful to separate two audiences. Development of the NoFlo UI is only necessary if you want to hack on the UI itself, and it is not necessary for making apps with FBP.

For building the UI there is a Dockerfile, and there is also an automatically built image on Docker Hub. The two commands are:

docker build -t noflo-ui .

and

docker run -d -p 9999:80 noflo-ui

Once the server is running, the UI is at http://localhost:9999/index.html. The Dockerfile behind this is a two stage build: a node:lts-alpine builder with git and python installed, npm ci and npm run build, and then an nginx image that serves the built browser directory.

Working directly against a checkout is also documented. You need a checkout of the repository, a working Node.js installation, and at least version 3 of the npm package manager. Then npm install pulls the development dependencies, npm run build produces a new version, and the README notes you have to run that build command as an administrator on Windows. You serve the UI with a webserver and open the URL in a browser, with npm start as the example, or you run npm run dev to start a webpack dev server that rebuilds whenever a file changes.

The dependency list in package.json is telling about the technology choices: Polymer 3 with webcomponentsjs for the view layer, React 17 alongside it, CodeMirror 5 for editing, the fbp family of packages for the graph model and protocol, noflo packages for the runtime side, the-graph for the editor, and a patched fork of octo pulled from a git URL rather than from the registry.

Redux conventions expressed as a flow graph

The architecture section is the most interesting document in the repository, because it describes a design in a language the project is built on.

On a high level the noflo-ui architecture follows Redux conventions adapted to NoFlo, and the main data flow is written as an FBP graph:

Store OUT -> IN Middleware     # Store sends actions together with application state to middleware
Middleware NEW -> ACTION Store # Middleware can trigger new actions
Middleware PASS -> IN Reduce   # Actions go from middleware to reducers
Reduce OUT -> STATE Store      # Reducers produce a new state object that gets sent to store
Reduce OUT -> STATE View       # State also goes to the view
View ACTION -> ACTION Store    # View can trigger actions

The four components have clear roles. The Store keeps track of the latest application state and, on receiving new actions, sends them out to the middleware and reducer chain together with the latest state.

Middleware are components or graphs that interact with particular actions, and each middleware has exactly two options with an action: pass it along without modifying it, or capture it and trigger new actions. That is where side effects live, including talking to external web services, FBP runtime communications, and loading or saving data to the local IndexedDB. Middleware receive the current state and can read from it, but they only manipulate state by creating new actions, and some middleware act as generators, creating new actions based on external input.

Reducers receive actions and make changes to application state, and they must in effect be pure functions, where the same input state and action combination always produces the same new state. The View is the application's view layer, implemented with Polymer elements.

The actual flow is more detailed, and you can view and edit it in graphs/main.fbp, which is the closest thing this project has to an architecture diagram.

Where noflo-ui is the wrong tool

Three cases point elsewhere.

The first is a project that is not flow based. This is an environment for FBP, and if your application is an ordinary program then a general IDE, or a purpose built tool for your stack, is the answer.

The second is a team that wants a finished product rather than a platform. There is a hosted version, Flowhub at app.flowhub.io, and the README recommends it if you just want to create applications instead of building your own from source. That recommendation is worth taking at face value: running the UI yourself means owning the build, the deployment and the protocol compatibility.

The third is a runtime you cannot change. The editor is useful to you only insofar as your runtime speaks the FBP Network Protocol. If you cannot implement that protocol, the UI will connect to nothing, and the runtime information files will not help, because they are presentation rather than capability.

One more caution about the codebase itself. The README says in as many words that the architecture described is the one the project is aiming towards, that parts of the system are being refactored to fit it, and that all new functionality should be implemented following this architecture. That is a candid description of a codebase in transition, which is fine for a project with a stable protocol and a hosted option, and is a warning for anyone planning to build a product on top of the source.

Editorial conclusion

Adopt noflo-ui if you are working with FBP and want a visual editor that runs in the browser, works offline, and can drive a runtime you do not control, since the protocol boundary is what makes that possible. Do not adopt it if you are looking for a general IDE, and do not adopt it expecting the runtime to be included, because the UI is only the authoring and monitoring side. Verify three things first: which FBP runtime you will connect and whether it implements the network protocol, since the README says over five runtimes are known to work and the rest is yours to implement; how you will pass the connection to users, since live mode encodes protocol, address and secret in URL parameters; and that the licence and the third party pieces suit you, because the application is MIT while it embeds NoFlo, Polymer, React, the-graph and a patched fork of octo. The licence is MIT, the last push was on 2026-10-20, and the package version in the repository is 0.29.1.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. noflo/noflo-ui on GitHub
4. Project website
5. README