Flyde Visual Programming: Custom Nodes & Code Integration

Flyde is a visual, flow-based programming tool designed to complement your existing codebase. It allows you to build and execute visual programs within Node.js or frontend projects using TypeScript and JavaScript. Rather than replacing text-based coding, Flyde provides a higher-level abstraction where appropriate, helping developers of all experience levels manage complex tasks more efficiently.

Try It Online

The fastest way to experiment with Flyde is through the online [Playground](flyde.dev/playground/blog-generator). You can create and execute flows directly in your browser to see the visual editor and runtime library in action. It’s an ideal way to understand how these flows connect to your own code without requiring any local installation.

Run Locally

1. Install the Flyde VSCode extension from the marketplace.
2. Open your terminal and run mkdir my-flyde-project && cd my-flyde-project.
3. Open the new folder in VSCode.
4. Access the command palette (Ctrl+Shift+P) and select Flyde: New visual flow.
5. To link your flow to an existing project, refer to the “Integrating with Existing Code” documentation.

Modern software development relies heavily on asynchronous and concurrent operations, which can be difficult to manage in standard text-based code. Visual programming simplifies these patterns, making it easier to build, visualize, and debug complex logic.

With Flyde, less experienced team members can more easily understand and contribute to business logic. Meanwhile, experienced developers benefit from self-documenting diagrams that remain accurate, alongside new methods for debugging and performance optimization.

Flyde's Core Components

Creating Custom Nodes

Custom nodes allow you to extend Flyde with your own specialized logic. They are useful for everything from simple control-flow helpers to complex business logic wrappers, enabling you to present existing code as modular, visual blocks. You can build custom nodes in three ways:

1. Code Nodes

Code nodes are the fundamental building blocks of Flyde. You define specific inputs, outputs, and the logic that triggers when the node runs.

To create a code node, export an object that implements InternalCodeNode from a .flyde.ts or .flyde.js file. This naming convention ensures the visual editor automatically detects and includes your node in the library.

A code node consists of two parts:

• Metadata: Defines how the node appears in the editor, including its name, description, inputs, outputs, and icon.
• Logic: The actual code executed during runtime.

Below is an example of a custom node that calculates the sum of two numbers:

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),
};

In the run function, the first argument contains the input values. The second argument provides the outputs as RxJS Subject objects. To send a value to an output, call next on the corresponding Subject.

Note: Flyde utilizes RxJS internally as an implementation detail. You do not need to be an RxJS expert to build custom nodes, as you will rarely need to interact with its full API.

The run function also supports a third argument for advanced utilities, such as the state object. This Map<string, any> allows a node to persist data throughout the lifetime of the flow.

This example calculates a running average by using state to remember previous values:

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);
  },
};

2. Visual Nodes

In Flyde, every flow acts as a visual node itself. This modularity allows you to import existing flows and use them as nodes within other flows.

For instance, if you create a flow named Add1.flyde that increments an input by one, you can find it later in the "nodes library -> view all" menu under the "Current project" section, ready for reuse.

3. Macro Nodes

Macro nodes are similar to code nodes but support "edit-time" configuration. Their runtime logic and visual appearance can change based on user settings in the editor. You can also build custom configuration interfaces for them. Several standard nodes, such as the "Conditional" node, are built as macros and use a custom UI loaded outside Flyde’s core.

Documentation for macro nodes is currently in development. For implementation examples, you can explore the flyde/stdlib repository. Each macro node requires a bundled React component to handle its configuration UI. These components must be bundled separately and export a window variable named __MacroNode__ID (replacing ID with the node's unique identifier). Until official guides are released, refer to the stdlib bundling configuration for technical details.

The Playground is the best place to start, as it offers numerous examples demonstrating the editor, the runtime, and custom code integration. Once you are familiar with the basics, install the VSCode extension to begin building flows and integrating them into your local projects.