@persistent-ai/fireflow-frontend (0.29.1)

Published 2026-08-18 14:34:12 +00:00 by ak

Set up this registry in your project .npmrc file:

@persistent-ai:registry=

To install the package using npm, run the following command:

npm install @persistent-ai/fireflow-frontend@0.29.1

or add it to the package.json file:

"@persistent-ai/fireflow-frontend": "0.29.1"

For more information on the npm registry, see the documentation.

@persistent-ai/fireflow-frontend

A powerful, React-based visual programming interface for the PersistentAI flow-based programming framework. This package provides a complete, feature-rich UI for designing, managing, and executing computational graphs with a focus on real-time collaboration and type safety.

Features

Visual Flow Editor: Intuitive drag-and-drop interface for designing computational flows
Real-time Synchronization: WebSocket-based updates ensure all changes are immediately reflected
Type-Safe Ports: Strong type checking for node connections with visual feedback
Interactive Debugging: Debug mode with breakpoints, step execution, and visual state tracking
Theming Support: Built-in light and dark mode with customizable node styling
Responsive Design: Adapts to different screen sizes and resolutions
Performance Optimized: Efficient rendering even with large and complex flows

Installation

# Before installing, make sure you have set up authentication for GitHub Packages
npm install @persistent-ai/fireflow-frontend
# or
yarn add @persistent-ai/fireflow-frontend
# or
pnpm add @persistent-ai/fireflow-frontend

Authentication for GitHub Packages

To use this package, you need to configure npm to authenticate with GitHub Packages:

Create a personal access token (PAT) with the read:packages scope on GitHub.
Add the following to your project's .npmrc file or to your global ~/.npmrc file:

@persistent-ai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT

Replace YOUR_GITHUB_PAT with your actual GitHub personal access token.

Basic Usage

To integrate the PersistentAI editor into your React application:

import {Flow} from '@persistent-ai/fireflow-frontend';
import {TrpcProvider} from '@persistent-ai/fireflow-trpc/client';
import {ThemeProvider, ZoomProvider, DndProvider} from '@persistent-ai/fireflow-frontend/providers';
import {ReactFlowProvider} from '@xyflow/react';

function App() {
    return (
        <RootProvider
            trpcURL={`ws://localhost:3001`}
            superjsonCustom={SuperJSON}
            nodeRegistry={NodeRegistry.getInstance()}
        >
            <div className="flex h-screen">
                <Sidebar
                    onFlowSelected={(flowId) => {
                        // For example, navigate to the selected flow
                        // navigate(`/flow/${flowId}`)
                    }}
                    enabledTabs={[
                        'flows', 
                        'nodes', 
                        'events', 
                        'variables', 
                        'debug', 
                        'settings', 
                        'help'
                    ]}
                />
                <div className="flex-1">
                    <Flow
                        {/* Flow id is optional */}
                        flowId={'your-flow-id'}
                    />
                </div>
            </div>
        </RootProvider>
    );
}

export default App;

Key Concepts

Flows

Flows are computational graphs made up of nodes and connections. Each flow can be created, saved, executed, and shared. The PersistentAI frontend provides a complete management system for flows with operations like:

Creating and editing flows
Managing flow metadata (name, description, tags)
Executing flows with real-time monitoring
Debugging with breakpoints and step execution

Nodes

Nodes are the building blocks of a flow. Each node has:

Input and output ports with type definitions
Configuration options
Visual styling based on category
Execution state indicators

Ports

Ports represent data inputs and outputs for nodes. The frontend supports:

Various port types (string, number, boolean, array, object, stream)
Type-safe connections between ports
Rich editing capabilities for different data types
Visual indicators for connection status

Development

Prerequisites

Node.js v22.x or higher
pnpm v10.x or higher

Local Development

# Clone the repository
git clone https://github.com/Persistent-AI/fireflow.git
cd fireflow

# Install dependencies
pnpm install

# Start the frontend development server
pnpm --filter @persistent-ai/fireflow-frontend run dev

Building

# Build the frontend package
pnpm --filter @persistent-ai/fireflow-frontend run build

Component Structure

The frontend is organized into several key component areas:

Flow: The main canvas component for visualizing and interacting with flows
Sidebar: Navigation and management interface with tabs for flows, nodes, and settings
Nodes: Visual representations of computational units with configurable ports
Controls: UI elements for flow execution, debugging, and management

Theming

PersistentAI frontend supports both light and dark themes out of the box. The theme can be toggled with the ThemeToggle component or programmatically via the ThemeProvider.

import { useTheme } from '@persistent-ai/fireflow-frontend';

function MyComponent() {
  const { theme, toggleTheme } = useTheme();
  
  return (
    <button onClick={toggleTheme}>
      Current theme: {theme}
    </button>
  );
}

Advanced Usage

Flow Subscription

The frontend automatically synchronizes with the backend using WebSocket subscriptions:

import { useFlowSubscription } from '@persistent-ai/fireflow-frontend';

function FlowSyncStatus() {
  const { status, isSubscribed, error } = useFlowSubscription();
  
  return (
    <div>
      Connection status: {status}
      {error && <div>Error: {error.message}</div>}
    </div>
  );
}

Execution Control

Control flow execution with the built-in hooks:

import { 
  createExecution, 
  startExecution, 
  pauseExecution,
  stepExecution
} from '@persistent-ai/fireflow-frontend';
import { useUnit } from 'effector-react';
import { $executionState } from '@persistent-ai/fireflow-frontend';

function ExecutionControls() {
  const { executionId, status, debugMode } = useUnit($executionState);
  
  return (
    <div>
      <button onClick={() => createExecution({ flowId: 'your-flow-id', debug: true })}>
        Create Execution
      </button>
      <button onClick={() => startExecution(executionId)}>
        Start
      </button>
      {/* Other execution controls */}
    </div>
  );
}

Browser Compatibility

PersistentAI frontend is compatible with modern browsers including:

Chrome/Edge (latest 2 versions)
Firefox (latest 2 versions)

Safari needs to investigate some issues. Internet Explorer is not supported.

Contributing

Contributions to PersistentAI are welcome! Please read our Contributing Guidelines before submitting a pull request.

License

BUSL-1.1 - Business Source License

This source code is licensed under the Business Source License 1.1 included in the file LICENSE.txt in the repository root directory. As of the Change Date specified in that file, in accordance with the Business Source License, use of this software will be governed by the Apache License, version 2.0.

@persistent-ai/fireflow-types: Core type definitions and decorators
@persistent-ai/fireflow-backend: Backend services for flow execution
@persistent-ai/fireflow-nodes: Collection of pre-built nodes
@persistent-ai/fireflow-trpc: tRPC API layer for type-safe communication

Dependencies

ID	Version
@ag-ui/client	^0.0.47
@ag-ui/core	^0.0.47
@assistant-ui/react	^0.12.19
@codemirror/autocomplete	^6.20.3
@codemirror/commands	^6.10.4
@codemirror/lang-html	^6.4.11
@codemirror/lang-javascript	^6.2.5
@codemirror/lang-json	^6.0.2
@codemirror/lang-markdown	^6.5.1
@codemirror/lang-python	^6.2.1
@codemirror/lang-sql	^6.10.0
@codemirror/lang-yaml	^6.1.3
@codemirror/language	^6.12.4
@codemirror/search	^6.7.1
@codemirror/state	^6.7.1
@codemirror/theme-one-dark	^6.1.3
@codemirror/view	^6.43.6
@copilotkit/react-core	^1.54.0
@dnd-kit/core	^6.3.1
@dnd-kit/sortable	^10.0.0
@dnd-kit/utilities	^3.2.2
@fontsource/inter	^5.2.8
@fontsource/jetbrains-mono	^5.2.8
@git-diff-view/file	^0.1.7
@git-diff-view/react	^0.1.7
@hookform/resolvers	^5.2.2
@mixmark-io/domino	^2.2.0
@modelcontextprotocol/sdk	^1.30.0
@persistent-ai/fireflow-agui	0.29.1
@persistent-ai/fireflow-agui-react	0.29.1
@persistent-ai/fireflow-bash	0.29.1
@persistent-ai/fireflow-console	0.29.1
@persistent-ai/fireflow-executor	0.29.1
@persistent-ai/fireflow-ff-grammar	0.29.1
@persistent-ai/fireflow-mcp	0.29.1
@persistent-ai/fireflow-nodes	0.29.1
@persistent-ai/fireflow-overcast	0.29.1
@persistent-ai/fireflow-sandbox	0.29.1
@persistent-ai/fireflow-search	0.29.1
@persistent-ai/fireflow-trpc	0.29.1
@persistent-ai/fireflow-types	0.29.1
@persistent-ai/fireflow-vfs	0.29.1
@persistent-ai/persistentai-api	0.29.1
@radix-ui/react-accordion	^1.2.12
@radix-ui/react-alert-dialog	^1.1.15
@radix-ui/react-checkbox	^1.3.3
@radix-ui/react-collapsible	^1.1.12
@radix-ui/react-context-menu	^2.2.16
@radix-ui/react-dialog	^1.1.15
@radix-ui/react-dropdown-menu	^2.1.16
@radix-ui/react-icons	^1.3.2
@radix-ui/react-label	^2.1.8
@radix-ui/react-popover	^1.1.15
@radix-ui/react-progress	^1.1.8
@radix-ui/react-radio-group	^1.3.8
@radix-ui/react-scroll-area	^1.2.10
@radix-ui/react-select	^2.2.6
@radix-ui/react-separator	^1.1.8
@radix-ui/react-slider	^1.3.6
@radix-ui/react-slot	^1.2.4
@radix-ui/react-switch	^1.2.6
@radix-ui/react-tabs	^1.1.13
@radix-ui/react-tooltip	^1.2.8
@radix-ui/themes	^3.3.0
@tailwindcss/postcss	^4.2.2
@tailwindcss/typography	^0.5.19
@tanstack/react-query	^5.91.3
@tanstack/react-query-devtools	^5.91.3
@tanstack/react-virtual	^3.13.26
@tonconnect/ui-react	^2.4.2
@trpc/client	^11.18.0
@trpc/react-query	^11.18.0
@trpc/server	^11.18.0
@trpc/tanstack-react-query	^11.18.0
@types/color	^4.2.1
@types/d3-scale	^4.0.9
@xterm/addon-fit	^0.11.0
@xterm/addon-search	^0.16.0
@xterm/addon-web-links	^0.12.0
@xterm/xterm	^6.0.0
@xyflow/react	^12.10.2
@xyflow/system	^0.0.76
add	^2.0.6
ahooks	^3.9.6
class-variance-authority	^0.7.1
clsx	^2.1.1
cmdk	^1.1.1
codemirror	^6.0.2
color	^5.0.3
d3-scale	^4.0.2
date-fns	^4.1.0
effector	^23.4.4
effector-react	^23.3.0
fast-deep-equal	^3.1.3
fast-json-patch	^3.1.1
framer-motion	^12.38.0
katex	^0.16.40
leaflet	^1.9.4
lucide-react	^0.577.0
nanoid	^5.1.7
nanoid-dictionary	^5.0.0
patronum	^2.3.0
penpal	^7.0.6
react	^19.2.4
react-color	^2.19.3
react-colorful	^5.6.1
react-day-picker	^10.0.1
react-dom	^19.2.4
react-hook-form	^7.74.0
react-json-view-lite	^2.5.0
react-leaflet	^5.0.0
react-markdown	^10.1.0
react-number-format	^5.4.4
react-pdf	^10.4.1
react-router-dom	^7.13.1
reflect-metadata	^0.2.2
rehype-katex	^7.0.1
rehype-raw	^7.0.0
rehype-sanitize	^6.0.0
remark-gfm	^4.0.1
remark-math	^6.0.0
rxjs	7.8.1
sonner	^2.0.7
superjson	^2.2.6
tailwind-merge	^3.5.0
tailwindcss-animate	^1.0.7
uri-template	^2.0.0
use-sync-external-store	^1.2.0
viem	^2.48.4
wagmi	^3.6.4
xterm-readline	^1.2.2
yaml	^2.8.2
zod	^3.25.76
zod-to-json-schema	^3.25.1

Development Dependencies

ID	Version
@babel/plugin-proposal-decorators	^7.29.0
@babel/plugin-transform-class-properties	^7.28.6
@eslint/js	^10.0.1
@persistent-ai/typescript-config	0.29.1
@rolldown/plugin-babel	^0.2.0
@svgr/core	^8.1.0
@types/leaflet	^1.9.21
@types/node	^25.5.0
@types/react	^19.2.14
@types/react-color	^3.0.13
@types/react-dom	^19.2.3
@vitejs/plugin-react	^6.0.1
autoprefixer	^10.4.27
baseline-browser-mapping	^2.10.9
effector-logger	^0.15.0
esbuild	^0.27.4
eslint	^10.1.0
eslint-plugin-react-hooks	^7.0.1
eslint-plugin-react-refresh	^0.5.2
globals	^17.4.0
path-browserify	^1.0.1
postcss	^8.5.8
postcss-import	^16.1.1
rollup-plugin-node-polyfills	^0.2.1
tailwindcss	^3.4.19
typescript-eslint	^8.57.1
vite-plugin-circullar-dependency	^0.0.4
vite-plugin-node-polyfills	^0.26.0
vite-plugin-static-copy	^3.3.0
vite-plugin-svgr	^5.2.0

Peer Dependencies

ID	Version
@trpc/client	^11.18.0
@trpc/react-query	^11.18.0
@trpc/server	^11.18.0
@trpc/tanstack-react-query	^11.18.0
@xyflow/react	^12.10.2
@xyflow/system	^0.0.76
effector	^23.4.4
effector-react	^23.3.0
react	^19.2.4
react-color	^2.19.3
react-dom	^19.2.4
superjson	^2.2.6
use-sync-external-store	^1.2.0
viem	^2.48.4
wagmi	>=2.15.2

Details

npm

2026-08-18 14:34:12 +00:00

1

Project Site

BUSL-1.1

3.1 MiB

Assets (1)

fireflow-frontend-0.29.1.tgz 3.1 MiB

Versions (5) View all

0.29.4

2026-08-18

0.29.1

2026-08-18

0.29.0

2026-08-18

0.28.0

2026-08-17

0.26.2

2026-08-10

@persistent-ai/fireflow-frontend (0.29.1)

Installation

About this package

@persistent-ai/fireflow-frontend

Features

Installation

Authentication for GitHub Packages

Basic Usage

Key Concepts

Flows

Nodes

Ports

Development

Prerequisites

Local Development

Building

Component Structure

Theming

Advanced Usage

Flow Subscription

Execution Control

Browser Compatibility

Contributing

License

Related Packages

Dependencies