Rete.js: Visual Programming Framework

Common errors

• Type instantiation is excessively deep and possibly infinite. ts(2589)

  cause Using an older TypeScript version (below 4.7) with Rete.js v2.
  fix Upgrade TypeScript to version 4.7 or higher. If not possible, use `@ts-ignore` for the `use` method as a temporary workaround.

• Error: Cannot find module 'rete' or Cannot resolve module 'rete'

  cause Incorrect package installation or module resolution issues in a CJS environment when expecting ESM.
  fix Ensure `rete` and its necessary plugins are installed via `npm install rete rete-area-plugin rete-connection-plugin rete-react-plugin ...`. For CJS, ensure your bundler (Webpack, Rollup) or Node.js environment is configured to handle ESM imports correctly, or explicitly use `require()` if the package provides a CJS entry point. Modern Rete.js is ESM-first.

• Editor does not render or appears blank until window resize.

  cause The rendering container's dimensions might not be fully calculated or applied when the editor/area is initialized, especially in component lifecycle hooks (e.g., `ngAfterViewInit` in Angular).
  fix Wrap the editor/area initialization in a `setTimeout` with a small delay (e.g., 0ms or 10ms) to ensure the DOM has settled. Alternatively, manually call `area.resize()` after initialization if the container's dimensions are known.

Warnings

• breaking Rete.js v2 introduces significant architectural changes and breaking changes compared to v1, including a TypeScript-first design, a new plugin system, and a different approach to node and component creation. Migration requires substantial code refactoring.
  Fix: Consult the official Rete.js v2 Migration guide and documentation. The `Component` abstraction from v1 is replaced with more flexible node creation. Plugins are now classes and connected differently.
• gotcha Direct mutation of arrays returned by `editor.getNodes()` or `editor.getConnections()` might lead to unexpected behavior. These methods now return copies to prevent external interference with the editor's internal state.
  Fix: Always treat arrays returned by `getNodes()` and `getConnections()` as immutable. If modifications are needed, perform them on a copied array or use the editor's API for adding/removing elements.
• gotcha Rete.js v2 relies heavily on TypeScript for improved developer experience and type safety. While usable with plain JavaScript, the developer experience (DX) will be significantly poorer due to the lack of type inference and stricter typing in the framework's design.
  Fix: For optimal development experience, use TypeScript (version 4.7 or higher is recommended) with Rete.js.
• gotcha Performance issues can arise with a large number of nodes, especially in rendering-intensive scenarios. Synchronous operations or complex node rendering can block the main thread or cause low FPS.
  Fix: Optimize by connecting plugins only when needed, simplifying node rendering at low zoom levels (Level of Detail - LOD), and being mindful of expensive operations within node components. Implement `OnPush` change detection for Angular-based renderers where applicable.

Install

• npm install rete npm
• yarn add rete yarn
• pnpm add rete pnpm

Imports

• NodeEditor
  wrong:

  const { NodeEditor } = require('rete')

  correct:

  import { NodeEditor } from 'rete'

  Rete.js v2 is primarily designed with TypeScript and ESM in mind. While CJS is supported, modern projects should use ESM imports.
• GetSchemes

  import { GetSchemes, ClassicPreset } from 'rete'

  Used with TypeScript to define the schema for nodes and connections, ensuring type inference across plugins. `ClassicPreset` provides common interfaces for building nodes and connections.
• Connection
  wrong:

  import { Connection } from 'rete'; const connection = new Connection(...)

  correct:

  import { ClassicPreset } from 'rete'; const connection = new ClassicPreset.Connection(sourceNode, 'portKey', targetNode, 'portKey')

  In Rete.js v2, `ClassicPreset` encapsulates the standard Node and Connection implementations for convenience and type safety. Direct instantiation of `Connection` from 'rete' is generally not the intended pattern for basic usage.

Quickstart

This quickstart demonstrates how to set up a basic Rete.js editor with a custom node, two instances of that node, and a connection between them using the React renderer. It highlights the use of `NodeEditor`, `AreaPlugin`, `ConnectionPlugin`, and `ReactPlugin` with `ClassicPreset` for defining schemes and components.

import { NodeEditor, GetSchemes, ClassicPreset } from 'rete';
import { AreaPlugin, AreaExtensions } from 'rete-area-plugin';
import { ConnectionPlugin } from 'rete-connection-plugin';
import { ReactPlugin, Presets, ReactArea2D } from 'rete-react-plugin';
import { createRoot } from 'react-dom/client';

type Schemes = GetSchemes<
  ClassicPreset.Node,
  ClassicPreset.Connection<ClassicPreset.Node, ClassicPreset.Node>
>;
type AreaExtra = ReactArea2D<Schemes>;

const socket = new ClassicPreset.Socket('Number');

class MyNode extends ClassicPreset.Node {
  width = 180;
  height = 120;
  constructor(name: string, numValue: number = 0) {
    super(name);
    this.addControl('value', new ClassicPreset.InputControl('number', { initialValue: numValue }));
    this.addOutput('num', new ClassicPreset.Output(socket, 'Number'));
  }
}

async function createEditor(container: HTMLElement) {
  const editor = new NodeEditor<Schemes>();
  const area = new AreaPlugin<Schemes, AreaExtra>(container);
  const connection = new ConnectionPlugin<Schemes, AreaExtra>();
  const render = new ReactPlugin<Schemes, AreaExtra>();

  AreaExtensions.zoomAt(area, editor.getNodes());
  AreaExtensions.simpleNodesOrder(area);

  render.addPreset(Presets.contextMenu.setup());
  render.addPreset(Presets.classic.setup());

  editor.use(area);
  area.use(connection);
  area.use(render);

  const nodeA = new MyNode('A', 10);
  const nodeB = new MyNode('B', 20);

  await editor.addNode(nodeA);
  await editor.addNode(nodeB);
  await area.translate(nodeA.id, { x: 0, y: 0 });
  await area.translate(nodeB.id, { x: 250, y: 0 });

  const connectionAtoB = new ClassicPreset.Connection(nodeA, 'num', nodeB, 'num');
  await editor.addConnection(connectionAtoB);

  // Render the editor
  const root = createRoot(container);
  root.render(<ReactArea2D area={area} 
    // Pass extra props if needed
  />);

  console.log('Rete.js editor initialized with two nodes and a connection.');
  return editor;
}

// To run this in a browser:
// const container = document.getElementById('rete-container');
// if (container) { createEditor(container); }