@persistent-ai/fireflow-backend (0.28.0)

Published 2026-08-17 13:00:54 +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-backend@0.28.0

or add it to the package.json file:

"@persistent-ai/fireflow-backend": "0.28.0"

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

@persistent-ai/fireflow-backend

The backend server component for PersistentAI - a flow-based programming framework. This package provides the WebSocket server implementation that powers real-time communication between clients and the PersistentAI execution engine.

Overview

@persistent-ai/fireflow-backend delivers:

WebSocket Server: Real-time communication server using WebSockets
tRPC Integration: End-to-end type-safe API implementation
Execution Engine: Hosts the flow execution infrastructure
Polyfill Support: Ensures compatibility across different environments
Node Registry: Manages available computational nodes
Data Persistence: Supports both in-memory and PostgreSQL storage options

This backend server acts as the central hub for PersistentAI, enabling flow creation, execution, debugging, and real-time event propagation between clients and the computational engine.

Installation

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

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.

Usage

Starting the Server

The simplest way to start the server:

import { init } from '@persistent-ai/fireflow-trpc/server'
import { wsServer } from '@persistent-ai/fireflow-backend'

// Initialize the tRPC context and stores
await init()

// Start the WebSocket server
wsServer()

Environment Variables

PersistentAI Backend can be configured through environment variables. You can set these in a .env file in the project root or provide them directly when running the server.

Server Configuration

Variable	Description	Default	Example
`TRPC_SERVER_HOST`	Host address for the tRPC server	`localhost`	`0.0.0.0`
`TRPC_SERVER_PORT`	Port for the tRPC server	`3001`	`4000`

Keep-Alive Settings

Variable	Description	Default	Example
`TRPC_SERVER_KEEP_ALIVE_ENABLED`	Enable/disable WebSocket keep-alive	`true`	`false`
`TRPC_SERVER_KEEP_ALIVE_PING_MS`	Interval for sending ping messages (ms)	`5000`	`10000`
`TRPC_SERVER_KEEP_ALIVE_PONG_WAIT_MS`	Timeout for awaiting pong response (ms)	`10000`	`20000`

Database Configuration

Variable	Description	Default	Example
`DATABASE_URL`	PostgreSQL connection string	`postgres://postgres@localhost:5432/postgres?sslmode=disable`	`postgres://user:password@host:5432/dbname?sslmode=require`

Authentication Settings

Variable	Description	Default	Example
`AUTH_ENABLED`	Enable/disable authentication	`false`	`true`
`AUTH_DEV_MODE`	Enable development mode for authentication	`false`	`true`
`PERSISTENTAI_AUTH_ENABLED`	Enable PersistentAI authentication	`false`	`true`
`PERSISTENTAI_API_URL`	URL for the PersistentAI GraphQL API	`http://localhost:9151/graphql`	`https://api.persistentai.com/graphql`

Example .env Files

Basic Configuration:

# Basic server setup
TRPC_SERVER_HOST=localhost
TRPC_SERVER_PORT=3001
DATABASE_URL=postgres://postgres:postgres@localhost:5432/fireflow

Production Configuration:

# Production setup with authentication
TRPC_SERVER_HOST=0.0.0.0
TRPC_SERVER_PORT=3001
TRPC_SERVER_KEEP_ALIVE_ENABLED=true
TRPC_SERVER_KEEP_ALIVE_PING_MS=5000
TRPC_SERVER_KEEP_ALIVE_PONG_WAIT_MS=10000
DATABASE_URL=postgres://user:password@prod-db:5432/fireflow?sslmode=require
AUTH_ENABLED=true
PERSISTENTAI_AUTH_ENABLED=true
PERSISTENTAI_API_URL=https://api.persistentai.com/graphql

Development Configuration:

# Development setup
TRPC_SERVER_HOST=localhost
TRPC_SERVER_PORT=3001
DATABASE_URL=postgres://postgres@localhost:5432/postgres?sslmode=disable
AUTH_ENABLED=true
AUTH_DEV_MODE=true

Running with Docker

# Build the Docker image
docker build -t fireflow-backend -f packages/fireflow-backend/Dockerfile .

# Run the container
docker run -p 3001:3001 -e DATABASE_URL=postgres://postgres:postgres@host.docker.internal:5432/fireflow fireflow-backend

Server Features

WebSocket Communication

The backend creates a WebSocket server that handles:

tRPC Procedures: Type-safe API calls from clients
Real-time Subscriptions: Event streaming for flow execution
Connection Management: Tracking active connections and graceful shutdown

// The WebSocket server is initialized with:
const wss = new WebSocketServer({
  port: 3001,
})

// tRPC handler is applied to provide type-safe communication
const handler = applyWSSHandler({
  wss,
  router: appRouter,
  createContext,
})

Text Encoder/Decoder Stream Polyfills

The package includes polyfills for TextEncoderStream and TextDecoderStream to ensure compatibility across different Node.js environments:

// Apply polyfills when needed
import { setupPolyfills } from '@persistent-ai/fireflow-backend'

setupPolyfills()

Development

To run the backend in development mode with hot reloading:

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

# Install dependencies
pnpm install

# Start the backend in development mode
pnpm --filter @persistent-ai/fireflow-backend run dev

Building for Production

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

# Start the production server
pnpm --filter @persistent-ai/fireflow-backend run start

Testing

# Run tests
pnpm --filter @persistent-ai/fireflow-backend run test

# Run tests with coverage
pnpm --filter @persistent-ai/fireflow-backend run test:coverage

API Documentation

This package primarily serves as an infrastructure component, with most user-facing APIs being provided through the @persistent-ai/fireflow-trpc package. Key exports include:

wsServer(): Function to initialize and start the WebSocket server
setupPolyfills(): Function to apply necessary polyfills for streaming functionality

License

BUSL-1.1 - Business Source License

@persistent-ai/fireflow-types: Core type definitions and decorators
@persistent-ai/fireflow-frontend: Frontend components for visual flow programming
@persistent-ai/fireflow-trpc: tRPC API layer for type-safe communication
@persistent-ai/fireflow-nodes: Collection of pre-built nodes

Dependencies

ID	Version
@mixmark-io/domino	^2.2.0
@persistent-ai/fireflow-nodes	0.28.0
@persistent-ai/fireflow-trpc	0.28.0
@persistent-ai/fireflow-types	0.28.0
@persistent-ai/fireflow-vfs	0.28.0
@trpc/client	^11.18.0
@trpc/server	^11.18.0
@types/ws	^8.18.1
bigint-crypto-utils	^3.3.0
cors	^2.8.6
dotenv	^17.3.1
esm	^3.2.25
prom-client	^15.1.3
superjson	^2.2.6
ws	^8.21.3
yaml	^2.8.2

Development Dependencies

ID	Version
@persistent-ai/typescript-config	0.28.0
@types/cors	^2.8.19
@types/node	^25.5.0
vite-plugin-top-level-await	^1.6.0

Details

npm

2026-08-17 13:00:54 +00:00

1

Project Site

BUSL-1.1

6.7 MiB

Assets (1)

fireflow-backend-0.28.0.tgz 6.7 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-backend (0.28.0)

Installation

About this package

@persistent-ai/fireflow-backend

Overview

Installation

Authentication for GitHub Packages

Usage

Starting the Server

Environment Variables

Server Configuration

Keep-Alive Settings

Database Configuration

Authentication Settings

Example .env Files

Running with Docker

Server Features

WebSocket Communication

Text Encoder/Decoder Stream Polyfills

Development

Building for Production

Testing

API Documentation

License

Related Packages

Dependencies