
# Introduction

Flyde is visual, flow-based, programming toolkit that **integrates with your existing code**. It allows you to create and run visual programs.

Flyde integrates with TypeScript (and JavaScript) on Node.js and frontend projects.

## Quick Start

### Playground

The easiest way to experiment with Flyde is to visit the [online playground](https://flyde.dev/playground), which allows you to create and run flows in the browser.

### Running locally

1. Install the [VSCode extension](https://marketplace.visualstudio.com/items?itemName=flyde.flyde-vscode)
2. `mkdir my-flyde-project && cd my-flyde-project`
3. Open your project in VSCode
4. Command Palette (Ctrl+Shift+P) -> `Flyde: New visual flow`
5. Check out the [Integrating with Existing Code](./integrate-flows) guide to learn how to integrate your flows with your code

## Motivation

Modern development involves asynchronous and concurrency actions, which are more difficult to convey with text-based coding, and **easier, and more intuitive** to build, visualize and debug using a visual programming language.

Flyde was built **not to replace textual programming**, but augment it with a higher-level abstraction, **only when it makes sense to.**

Flyde makes it easier for **less skilled technical members to understand, and even contribute**, to business logic. It helps more seasoned developers by **having an always-correct diagram** of the program, as well as open new ways to troubleshoot functional and performance issues.

## Overview

Flyde's main building blocks are:

- .flyde files, which represent Flyde flows. They are YAML files behind the scenes and describe which nodes are in the flow, and how they are connected.
- The visual flow editor, which edits .flyde files. Available as a [VSCode extension](https://marketplace.visualstudio.com/items?itemName=flyde.flyde-vscode)
- The runtime library, an npm package `@flyde/loader`, which runs loads and runs .flyde files. Both on NodeJS and the browser (via a webpack loader)
- The standard library, an npm package `@flyde/nodes`, which contains a set of built-in nodes that can be used to create flows. Note: `@flyde/loader` depends on `@flyde/nodes`, so you don't need to install it separately.

## Getting Started

If you want to learn how to integrate Flyde with your code, jump straight to the the [Integrating with Existing Code](./integrate-flows) guide.

The playground has many examples and showcases not only the visual editor, but also the runtime library, and how to integrate it with your own code.

After you've played with the playground, you can install the VSCode extension, and start creating your own flows and integrating them with your code.

Read more about Flyde's core concepts in the next article: [Core Concepts](./core-concepts).


Get started with Flyde, a visual, flow-based programming toolkit that integrates with your existing code

Introduction


# Core Concepts

This article introduces some of the core concepts of Flyde.
:::tip
A deeper dive into each concept is available in the [advanced concepts](../advanced-concepts) article.
:::

## Nodes

Each node in Flyde is an isolated, modular unit that runs some logic when it is executed.
A node has **inputs** and **outputs** that allow it to interact with other nodes.

When a node runs, it can read the values of its inputs, and emit values to its outputs. The logic of a node is implemented either using code (TypeScript or JavaScript), or using Flyde, by grouping other nodes together.

For example, a node that adds two numbers together, will have two inputs, and one output, and will emit the sum of the two inputs to its output, once both inputs are received values.

Unlike regular functions, nodes can have multiple outputs, and can emit values to their outputs multiple times. For example, a node might receive a tuple of values, and emit each value to a different output.

## Connections

Nodes are connected together using **connections**. Connections are the wires that connect nodes together, and allow them to communicate. Each connection connects an output of one node, to an input of another node.

Whenever a node emits a value to one of its outputs, the value is sent to all the inputs of nodes that are connected to that output. The connected nodes will receive emitted value.

## Flow

A Flyde flow consists of **nodes** and **connections** between them. Nodes are the building blocks of a flow, and connections are the wires that connect them together.

A flow can also have **inputs** and **outputs** that allow it to interact with the outside world.

![Flyde Core Concepts](/docs/concepts-overview.png)


Learn about the fundamental concepts of Flyde: nodes, connections, and flows

Core Concepts


# Built-in Nodes Overview

:::warning
This article is a work in progress. It will be updated with more information soon.
:::

Flyde comes with a set of built-in nodes that can be used to build flows. All of these nodes can be found in the [standard library](https://github.com/flydelabs/flyde/tree/main/nodes) and are available as an npm package `@flyde/nodes`.

## Control Flow

### Conditional

### Switch

### Loop List

## Value

This is Flyde's version of a constant. It emits a single value to its output.

##


Overview of the standard library nodes available in Flyde

Built-in Nodes


# Integrating with Existing Code

A core tenet of Flyde is that it should **integrate with existing code, and not replace it**.

To achieve this, Flyde provides a runtime library that allows you to load and run .flyde files, and a webpack loader that allows you to load .flyde files directly from your code. Also, custom nodes can be implemented using TypeScript or JavaScript (more on that in the [custom nodes article](/docs/custom-nodes)).

For example, given a .flyde flow that converts Celsius to Fahrenheit:

![Celsius to Fahrenheit flow](/docs/cel-to-fah.png)

You can load and run it from your code as following:

```ts
import { runFlow } from "@flyde/loader";
import path from "path";

// Execute the flow directly with inputs
const result = await runFlow(path.join(__dirname, "celsius-to-fahrenheit.flyde"), {
  celsius: 0 // "celsius" is a main input in the flow
});

console.log(result.fahrenheit); // 32
```

The `runFlow` function directly returns the result of the flow execution.

For more advanced use cases, you can use the `loadFlow` function to get more control over execution:

```ts
import { loadFlow } from "@flyde/loader";

const execute = await loadFlow("./celsius-to-fahrenheit.flyde");
const { result } = execute(inputs, {
  onOutputs: (key, value) => {
    console.log(`output with key ${key} emitted value ${value}`);
  },
});
```

The example above assumes a Node.js environment. Loading Flyde in a browser environment is possible, but not yet documented. Checkout the website's source code, [here](https://github.com/flydelabs/flyde/blob/main/website/src/pages/_examples.ts) and [here](https://github.com/flydelabs/flyde/blob/main/website/docusaurus.config.js#L18) for an example of how to do it.

:::note
Learn more about the lifecycle of a flow in the [advanced concepts article](./advanced-concepts).
:::

Another key method of intgrating with existing code is by creating your own custom nodes. Learn more about that in the [custom nodes article](/docs/custom-nodes).

Learn how to integrate Flyde flows into your existing codebase

Integrating Flows


# Creating Custom Nodes

Custom nodes allow you to extend Flyde's building blocks with your own logic.  
Use-cases can vary from control flow utilities, and up to business logic wrappers that expose your existing code-base in a modular, and visual way.

Custom nodes can be built in 3 ways:

- Code nodes - the simplest building block of Flyde. It declares its inputs and outputs, and runs some logic when it is executed.
- Visual nodes - a group of nodes that are grouped together visually, and can be reused as a single node.
- Macro nodes - macro nodes are like code nodes but with "edit-time" configuration. The runtime logic and visual representation of a macro node can be different depending on the configuration. The UI for editing the configuration of a macro node is also customizable. Some of the standard library nodes are implemented as macro nodes. For example, the "Conditional" node is a Macro Node that loads a custom UI, which is defined and loaded externally from Flyde's core.

## Custom Code Nodes

A Flyde custom code node can be created by exporting an object that implements the `InternalCodeNode` interface from a TypeScript/JavaScript file ending with `.flyde.ts` or `.flyde.js`. This convention helps the visual editor suggest your custom node when exploring the nodes library.

A custom code node consists of 2 parts:

- Its metadata, which is used to describe the node in the visual editor. This includes the node's name, description, inputs, outputs, and icon.
- Its logic, which is the code that runs when the node is executed.

The following example shows how to create a custom code node that adds two numbers together:

```ts
import { InternalCodeNode } from "@flyde/core";

export const Add: InternalCodeNode = {
  id: "Add",
  description: "Emits the sum of two numbers",
  inputs: {
    n1: { description: "First number to add" },
    n2: { description: "Second number to add" },
  },
  outputs: { sum: { description: "The sum of n1 and n2" } },
  run: ({ n1, n2 }, { sum }) => sum.next(n1 + n2),
};
```

The first argument of the `run` function is an object containing the values of the inputs of the node when it is being executed. The second argument is an object containing the outputs of the node, as [RxJS](https://rxjs.dev/) `Subject`s. The `run` function can emit values to the outputs of the node by calling `next` on the corresponding `Subject`.

:::note
Flyde use of RxJS is _very_ simplistic and should be treated as a mere implementation detail. You don't need to know RxJS to create custom nodes. Neither should you rely on a full RxJS API being available in your custom nodes.
:::

The `run` function also accepts a third argument, which is an object containing advanced utilities to help author more complex custom nodes. One of these utilities is the `state` object, which gives the node access to state that will be available to it while the flow is running. The `state` object is `Map<string, any>`.

For example, the following custom node will emit the average of all the numbers it received since the flow started:

```ts
import { InternalCodeNode } from "@flyde/core";

export const Average: InternalCodeNode = {
  id: "Average",
  description: "Emits the average of all the numbers it received",
  inputs: { n: { description: "Number to add to the average" } },
  outputs: { average: { description: "The average of all the numbers" } },
  run: ({ n }, { average }, { state }) => {
    const numbers = state.get("numbers") ?? [];
    numbers.push(n);
    state.set("numbers", numbers);
    average.next(numbers.reduce((a, b) => a + b, 0) / numbers.length);
  },
};
```

For more examples, please see how the standard library implemented. You can view it here on GitHub: [flyde/stdlib](https://github.com/flydelabs/flyde/tree/main/stdlib).

## Custom Visual Nodes

In Flyde, every Flow is also a visual node, this means you can import and use other flows as nodes in your flow.

For example, if you create a flow with 1 input and 1 output, which adds 1 to the input, as following:

![Custom visual node example](/docs/custom-nodes__visual.png)

It will appear on the "Current project" section of the "nodes library -> view all" modal:

![Using custom visual node](/docs/custom-nodes__using-visual.gif)

## Macro Nodes

:::info
Macro node docs are still in progress. Please refer to the [flyde/stdlib](https://github.com/flydelabs/flyde/tree/main/stdlib) for examples.
:::

Each macro node is expected to expose an already bundled React component that can render and edit the node's configuration.
Each component is expected to be bundled separately, and export a window variable named `__MacroNode__ID`, which is the ID of the macro node.  

Until this is properly documented, and potentially abstracted, you may follow the stdlib's bundle config to see how it is done there - https://github.com/flydelabs/flyde/blob/main/stdlib/package.json#L52.









Learn how to create custom code nodes, visual nodes, and macro nodes in Flyde

Creating Custom Nodes


# Testing, Deploying & Versioning

Although Flyde is a visual programming language, it's just a library. This means that **you can test, version control and deploy your flows using any tool you like.**

A great example is the standard library, which has some tests that use Flyde flows as fixtures. The flows are loaded and then tested like any other code. You can find them [here](https://github.com/flydelabs/flyde/blob/main/stdlib/src/Values/Values.spec.ts).

Same goes for deployment, you can use any deployment tool you like. You can use a CI/CD pipeline, a serverless framework, or even a simple bash script.

:::info
If you're looking for a way to deploy your flows as a service, check out [Flowcode](https://www.getflowcode.io?ref=flyde-docs). It is a fully hosted API and workflow builder based on Flyde.
:::


Best practices for testing and deploying Flyde flows

Testing & Deploying


# Advanced Concepts

Flyde was built with flexibility and power in mind. To enable that, Flyde tries to be reactive and declarative.
This enables building custom flows and custom nodes with little overhead and boilerplate.

## Node Instance Input Modes

Each input of each instance of a node in a flow can be in one of the following modes:

### "Queued"

New values received by the input will be queued, and each time the node runs, it will consume the next value from the queue.

Queued inputs are great if you need to "buffer" values, or if you want to make sure that no values are lost.

### "Sticky"

The input will keep its last value throughout it's parent node/flow's lifecycle. Each new value received by the input will replace the previous value.

Sticky inputs are great for values that will act as "dynamic configuration" for the node.

## Node Lifecycle

A Node in Flyde can be in one of the following states:

### "Idle"

The node is not performing any work. It stays idle until all its required inputs are satisfied.

### "Running"

When a node starts running, it'll "consume" the values from its inputs and perform its work. This means that any queued inputs will be consumed, and any sticky inputs will be read.

While a node is running, new values will only take effect on the next time it runs, unless they are set as a "reactive input". More on that below.

A node can have implicit or explicit completion triggers. More on that below.

### 'Completed' and 'Error'

While not real "states", a node can be in a "completed" state or an "error" state. A node is considered "completed" when it has finished running and has no more work to do. A node is considered in an "error" state when it has thrown an error during its run. Both completed and error states are transient, and a node will go back to the "idle" state after it has completed or errored.

## Node Completion

### Implicit Completion

A node will implicitly complete when it has no more work to do. For code nodes, it means that their `run` method has returned. In case the `run` method returns a promise, the node will implicitly complete when the promise resolves.

For visual nodes, it means that all of its children have completed.

Implicit completion is the default behavior for nodes.

### Explicit Completion

A node can declare it has explicit completion by declaring a "completionOutputs" property. This property is an array of output names that will trigger the node to complete when they emit a value. It also supports a `+` operator to declare that all outputs should trigger completion.

For example:

- `completionOutputs: ['output1', 'output2']` will trigger the node to complete when either `output1` or `output2` emit a value.
- `completionOutputs: ['n1+n2']` will trigger the node to complete when both `n1` AND `n2` emitted a value.
- `completionOutputs: ['n1+n2', 'n3']` will trigger the node to complete when both `n1` AND `n2`, OR just 'm3' emitted a value.

Visual nodes' completion outputs can be declared explicitly as well by right-clicking the node and selecting "Set Completion Outputs".

## Reactive Inputs

A node can declare that an input is "reactive". This means that the node will re-run when the input emits a new value, even if the node is already running.

A great example of when this is useful is a "debounce" node. Imagine a "debounce" node with 2 inputs: `value` and `delay`. Once a value is received, the node needs to remain in "running" state for the duration of the delay, and then emit the value. But if a node only accepts new values when it is idle, it will not be able to accept the new value of `value` until it has completed.

To solve this, we can mark the `value` input as "reactive", and the node will re-run when the `value` input emits a new value. Updating the `delay` input will not trigger a re-run, as it is not marked as "reactive", and will only take effect on the next time the node runs.

## "Manually" Triggering a Node

By default, a node will run when all of its inputs are satisfied. But sometimes you might want to control when a node runs more granularly. To do so, you may expose a "Trigger" input, which will act as a manual trigger for the node. If this input is connected, the node will only run when it receives a value on the "Trigger" input (and all other inputs are satisfied).

To expose the "trigger" input, right-click the node instance and select the "Show Trigger" option.

_[ TODO: Add a gif showing how to expose the trigger input]_

## Error Handling

When a node throws an error, it will be in an "error" state. The error will be displayed in the node's UI, and the error will be propagated to the parent node/flow.

To "catch" an error and avoid it from propagating, you can expose the "Error" special output.
To expose the "Error" output, right-click the node instance and select the "Show output Error" option.

_[ TODO: Add a gif showing how to expose the trigger input]_


Deep dive into advanced Flyde concepts and patterns

Advanced Concepts


# Third-Party Nodes

Flyde leverages the npm ecosystem to enable importing of third-party nodes into flows.

## Using Third-Party Nodes

To use a third-party node in your flow, you need to the npm package that contains the node. Flyde will automatically dependencies that contain Flyde nodes, and make them available in the node picker.

## Publishing Third-Party Nodes

To publish Flyde nodes to npm, you need to add a "flyde.exposes" property to your package.json - an array of globs that will contain Flyde nodes (either code nodes or visual nodes). Additionally, you should make sure that the package name starts with "flyde-".

This will hint to the Flyde editor that your package contains nodes, and it will automatically suggest them to the node library once the package is installed.

:::info
For better community discoverability, we recommend adding the "flyde" keyword to your package.json.
:::

### Example

```json
{
  "name": "flyde-my-nodes",
  "version": "1.0.0",
  "flyde": {
    "exposes": ["nodes/**/*.flyde.ts", "nodes/**/*.flyde"]
  }
}
```

:::note
Flyde's standard library is also published as an npm package, `@flyde/nodes`. You can use it as a reference for how to publish your own nodes.
:::


Learn how to install and use third-party nodes in Flyde

Third-party Nodes


# Troubleshooting

## Visual Debugger

Flyde comes with a visual debugger that can help you troubleshoot your flows. When using the "test flow" feature from the editor, you can see the flow's execution in real-time, and inspect the values of each node's inputs and outputs.

When running flows locally using the `@flyde/loader` package, the runtime will try to connect to the local debugger server running from the visual editor automatically. If you're running the visual editor locally, you can see the flow's execution in real-time, and inspect the values of each node's inputs and outputs.

## Extension Troubleshooting

If something in the extension is not working as expected, you can look for errors in VSCode's dev tools. To do so, open the command palette and search for "Developer: Toggle Developer Tools". This will open a new window with the dev tools, where you can see errors and logs from everything running in VSCode, including the Flyde extension.

## Flow Runtime Troubleshooting

### Verbose Logging

Behind the scenes, Flyde uses the `debug` package to log debug information. You can enable debug logs by setting the `DEBUG` environment variable to `flyde:*`. For example, on a Unix-like system, you can run the following command to enable debug logs:

```sh
DEBUG=flyde:* node my-flow.js
```

## Reporting Issues

We're always looking to improve Flyde, and we'd love to hear from you. If you find a bug, have a feature request, or just want to ask a question, feel free to:

- open an issue on the [Flyde GitHub repository](https://www.github.com/flydelabs/flyde)
- join our [Discord server](https://www.flyde.dev/discord) and ask in the #flyde channel


Common issues and solutions when working with Flyde

Troubleshooting


# Frequently Asked Questions

## What is the origin of the name "Flyde"?

"Flyde" means "flow" in Danish. Flow is a central concept in Flyde. And while we have no direct connection to Denmark, we appreciate the simplicity and functionality that Danish design often represents.

## Is Flyde "no-code"?

No. Flyde is a visual **programming** language, which means that it is a tool for creating software. While it may lower the barrier to entry for programming, just like assembly did to punch cards, and just like JavaScript did to C, it is still a programming language. If it has to be classified, it would be more accurate to call it a "low-code" tool, but even that is not a definition we're comfortable with.

## What about performance?

At the project's current stage, running a program using Flyde's runtime will be slower than running the same program written in TypeScript/JavaScript. The primary focus is on making the development experience as smooth as possible. We believe that the benefits of visual programming, such as increased readability and maintainability, will outweigh the performance cost for most use cases.

Moreover, once the project matures, many optimizations can be made to the runtime to improve performance. For example, we can compile the visual flow to a more efficient representation to avoid needing to interpret the flow at runtime. The runtime could be rewritten in a lower-level language, or even compiled to WebAssembly for better performance. These are all possibilities for the future.

## How Flyde relates to flow-based programming (FBP)?

Flyde is a visual programming language that is heavily inspired by flow-based programming (FBP). We came across J. Paul Morrison's (RIP) book "Flow-Based Programming" after we had already started working on Flyde, and we were thrilled to find that many of the concepts we had been developing were already well-established in the FBP community.

However, Flyde does not strictly adhere to the FBP paradigm. We have made some deviations from the traditional FBP model and do not see following FBP as a goal in itself. Instead, we aim to create a visual programming language that is practical and useful for modern software development.

## How does Flyde compare to other visual programming languages?

### NodeRED

Flyde integrates directly into TypeScript/JavaScript projects, acting as a visual layer within the code rather than an external service. It's designed to embed visual flows at any level of your application, from detailed business logic to overarching services, offering a seamless blend with existing codebases.

### Scratch

While Scratch is an excellent educational tool for beginners, Flyde is tailored for real developers. It adopts a functional, reactive approach and is designed to work within the ecosystems developers are already familiar with, like IDEs, without simplifying the complexity required for professional backend development.

### Enso

Enso targets data science with a unique IDE and programming language, focusing on data processing. In contrast, Flyde is application-centric, aiming to streamline backend development without introducing new tooling or languages, sticking closely to the existing TypeScript/JavaScript ecosystem.

### n8n / Zapier / Integromat / PipeDream

Unlike these automation platforms, which often work as closed systems for connecting APIs, Flyde is open-source and embeddable within your project. This gives developers the flexibility to craft detailed flows, from recursion to precise HTTP requests, offering a granular level of control and customization not typically available in no-code/low-code automation tools.


Learn Flyde