Pekfinger-RED 2

Pekfinger-RED (p-red) is a flow-based web-framework for Node-RED. It is based on Svelte and Vite.

It allows to create flow-based web applications using entrypoints, pages, events and a lot of wire. And the best: all apps are Progressive Web Apps (PWAs) by default.

⚠⚠⚠ This is still work in progress. So use with care. And please mind that no real documentation exists so far.

The framework is so far only used for internal projects. In our experience it runs quite stable though. Some features are still missing and obviously you will find bugs sooner or later. Thank you for reporting them.

Features

• Flow-based: Define pages and connect them like any other flow within Node-RED to define the flow of your web-page. One page might e.g. trigger an event which redirects the client to another page forwarding the necessary data for rendering. Apps are single page apps (SPA).
• Event-based: Define client and server events to communicate between your page and your flow.
• Visual editor: Define the structure of your page (nested components and their properties) through a visual editor (not WYSIWYG but reflects the structure of your page).
• Installable: All apps are PWAs by default.
• Custom layouts and components: Define custom (layout) components using svelte.
• I8n support: Define translations within your app / pages which are automatically used based on the browser language and / or a lang URL property. Access them using the _('my-key') notation.
• Serve static or dynamic content: Serve / stream content to the client using the web-ressource node.
• Persistent stores: Store data on the client to be used on next relaunch.
• Sessions: Automatic session handling.
• Authorization: Easily define an authorization flow by linking to a link-in node. If it returns access to the entrypoint (and the subsequent flow with its pages) is granted. Or redirect to a login / error page. You can define public pages as well which need no authorization.
• Plugins: Can be extended with plugins that either supply layouts and components or add extra functionality like content manipulation.
• HMR: Supports hot module replacement in development mode to quickly reflect changes on already loaded pages.

Getting started

Install p-red using the package manager of your choice like e.g. npm:

npm i pekfinger-red

Afterwards install a UI library for p-red like e.g. Avtryck-UI (a-ui) which is based on IBM's Carbon Design resp. carbon-components-svelte:

npm i avtryck-ui-for-p-red

You can then add entrypoints (URL's that can be accessed by the browser) and pages (representing what is rendered within the browser). Connect them as needed and add server events to trigger a flow on the server (each server event has it's own node-output). If a flow which was started by a server-event ends in another web-page node, the client will render this page. This is how navigation is implemented in p-red: flow-based.

Client events can be triggered using the web-event node to trigger some javascript code on the client side (like e.g. triggering a popup). The web-page UI has a visual editor where you can add components to your page, define it's properties and handle events. The UI should hopefully be self-explanatory. Give yourself some time to get accustomed to it. We tried to implement as many convenience features as possible.

The web-app config node is where you define on which network interface and port the app will run as well as some other things like e.g. globals. It is best practice to add the web-app with your first entrypoint. As long as you have only one web-app defined, this will be set automatically for other web-nodes afterwards.

Entrypoints define events as well. The default GET event is used for http-requests. All other events will be used for client-server or server-server communication (based on web sockets) and can be used to define a server-side API to be used by your app.

There are some advanced features like how to use the client library (client.trigger(eventName, data), server.trigger(eventName, data) or server.for(frame).trigger(eventName, data)), inline frames or custom code. Best chance to master them is to take a look at the kitchen sink example project (see "Trying Pekfinger-RED with Gitpod" below).

Trying Pekfinger-RED with Gitpod

If you want to test Pekfinger-RED you may run this project within Gitpod which is integrated into GitLab and just a click away. After your workspace is up and running, you need to run the following commands in order to get the current working example:

gitpod /workspace/pekfinger-red $ npm run setup
[...] 
gitpod /workspace/pekfinger-red $ npm run dev

You will see a message that 2 new ports have been opened. One is for Node-RED, the other is the example app.

This is the best documentation we have at the moment.

Support

Our appologies that we currently can only provide limited support through the GitLab issue tracker. We do our best to answer as quickly as possible.

If you have a business case please feel free to get in touch with us by mail ([email protected]).

Developer information

Uses SIR to define the node's UI.