FlowFuse Flow Renderer

A library to render Node-RED flows in a web page.

Installation

npm install @flowfuse/flow-renderer

development

All client-side code is in the index.js file for easy inclusion in a web page.

Run npm run demo to test the flow renderer in a browser.

Run npm run build to build a minimised version of the flow renderer. This will output the file index.min.js.

IMPORTANT: The minified version of the flow renderer should be built before committing changes to the repository.

Usage

Add the following script tag to your HTML file:

<script type="module" src="https://github.com/FlowFuse/flow-renderer/raw/main/public/flow-renderer/index.min.js"></script>

or wherever the script is located in your project

Next, add a container element to your HTML file and instantiate a flowRenderer. NOTE: flow-renderer is an ES Module and requires a modern browser to run. Script tags must have the type="module" attribute.

By default, the flow renderer will render the flow with gridLines, images, labels, zoom, autoZoom, and autoScroll enabled. linkLines are disabled by default.

To operate the zoom, use the mouse wheel + Ctrl or ⌘ key. To scroll the container vertically, use the mouse wheel without the Shift key. To scroll the container horizontally, use the mouse wheel + Shift key.

Basic example

<div id="nr-flow-1" class="flow-renderer" style="height: 300px"></div>

<script type="module">
  const renderer = new FlowRenderer()
  const container1 = document.getElementById('nr-flow-1');
  const flow = [{"id": "1001", "type": "inject", "x": 100, "y": 40, "wires": [["1002"]]}, {"id": "1002", "type": "debug", "x":300, "y": 40}]
  renderer.renderFlows(flow, { container: container1 })
</script>

Inline Options example

Options can be set by data attributes scope, grid-lines, zoom, images, link-lines, labels, auto-zoom, auto-scroll.

NOTE: To SET and option, the data attribute can simply be present on the container element. To UNSET an option, the data attribute must be set to false.

<div id="nr-flow-2" style="height: 300px" 
    data-scope="custom-css-scope"
    data-grid-lines
    data-zoom
    data-images
    data-link-lines="false"
    data-labels
    data-auto-zoom
    data-auto-scroll
></div>

<script type="module">
  const renderer = new FlowRenderer()
  const container2 = document.getElementById('nr-flow-2');
  const flow = [{"id": "1001", "type": "inject", "x": 100, "y": 40, "wires": [["1002"]]}, {"id": "1002", "type": "debug", "x":300, "y": 40}]
  renderer.renderFlows(flow, { container: container2 })
</script>

Full Options example

<div id="nr-flow-3" class="my-scope" style="height: 300px"></div>

const renderer = new FlowRenderer()
const container3 = document.getElementById('nr-flow-3');
const flow = [{"id": "1001", "type": "inject", "x": 100, "y": 40, "wires": [["1002"]]}, {"id": "1002", "type": "debug", "x":300, "y": 40}]
renderer.renderFlows(flow, {
    container: container3,
    scope: 'custom-css-scope', // scope for CSS
    gridLines: true, // show gridLines
    images: true, // show images
    linkLines: false, // show link lines
    labels: true, // show labels
    zoom: true, // enable zoom within the container
    autoZoom: true, // auto zoom to fit the flow within the container upon rendering (best fit, limited to 20% min, 100% max zoom)
    autoScroll: true, // auto scroll the leftmost node to the left of the container and the topmost node to the top of the container upon rendering
    flowId: undefined // Id of flow to display
})

Vue example

    <div id="app">
        <div ref="f1" class="flow-renderer"></div>
    </div>

    <script type="module">
        import { createApp } from 'https://unpkg.com/vue@3/dist/vue.esm-browser.js'
        import FlowRenderer from './index.js'
        createApp({
            mounted() {
                const flow = [{"id": "1001", "type": "inject", "x": 100, "y": 40, "wires": [["1002"]]}, {"id": "1002", "type": "debug", "x":300, "y": 40}]
                const renderer = new FlowRenderer()
                renderer.renderFlows(flow, { container: this.$refs.f1 })
            }
        }).mount('#app')
    </script>

Basic example comparing to flows

<div id="nr-flow-1" class="flow-renderer" style="height: 300px"></div>

<script type="module">
  const renderer = new FlowRenderer()
  const container1 = document.getElementById('nr-flow-1');
  const flow1 = [{"id": "1001", "type": "inject", "x": 100, "y": 40, "z": "9999", "wires": [["1002"]]}, {"id": "1002", "type": "debug", "x":300, "y": 40, "z": "9999"}]
  const flow2 = [{"id": "1001", "type": "inject", "x": 120, "y": 40, "z": "9999", "wires": [["1002"]]}, {"id": "1002", "type": "debug", "x":120, "y": 80, "z": "9999"}]
  renderer.compare([flow1, flow2], { container: container1 })
</script>

Acknowledgements

This project owes a huge thanks to Gerrit Riessen for his original works on node-red-flowviewer. It was this great contribution that started the ball rolling. Gerrit kindly allowed us relicense the parts we needed to use in this project.

Limitations

Only client-side rendering is currently supported
Mobile pinch zoom is not yet implemented
The flow renderer does not support the full range of contributed Node-RED nodes however they will render as a generic node type complete with the node's label.
The flow renderer does not always render the flows and nodes exactly as they appear in the Node-RED editor. This is due in part to being a client-side render with no server-side component to provide full context and partly due to the current limitations of the renderer itself.
The flow compare functionality is still in very early development and may not work as expected if the flows are too dissimilar or are not well formed exports from Node-RED.

Versioning

While the API is in development, the version number of this package will remain at 0.x.y. x will be incremented for breaking changes, y for new features and patches. Once the API is stable, the version number will be updated to 1.0.0 and full SemVer rules will be applied.

License

Apache-2.0