tersa

Tersa allows you to build AI workflows using a drag-and-drop canvas.

1. Add Nodes: Use the toolbar to place nodes on the canvas.
2. Connect Nodes: Drag from a node's output port to another node's input port to create a workflow.
3. Select Models: Choose from supported providers within the nodes.
4. Execute: Run the workflow to process data through the connected AI models.

To set up a local development environment for Tersa, ensure you have Node.js (v20+) and PNPM installed. Follow these steps to clone the repository, install dependencies, and start the development server.

# 1. Clone the repository
git clone https://github.com/vercel-labs/tersa.git
cd tersa

# 2. Install dependencies
pnpm install

# 3. Run the development server
pnpm dev

The Dropzone component uses a React Context (DropzoneContext) to share its configuration and current file state (src) with its children. This allows you to build conditional UIs that react to the upload state.

Common Pattern: Use DropzoneEmptyState when no files are present, and DropzoneContent when files have been selected. You can use the src prop on the parent Dropzone to control this transition.

const [files, setFiles] = useState<File[]>([]);

<Dropzone 
  src={files} 
  onDrop={(accepted) => setFiles(accepted)}
>
  {files.length === 0 ? (
    <DropzoneEmptyState />
  ) : (
    <DropzoneContent />
  )}
</Dropzone>

The editor features a slash command system. Typing / triggers a suggestion menu that allows users to quickly insert nodes like Headings, Lists, Tables, or Code Blocks.

The menu is powered by Fuse.js for fuzzy searching through defaultSlashSuggestions.

Default slash commands include:

• Text (paragraph)
• To-do List (taskList)
• Heading 1, Heading 2, Heading 3
• Bullet List and Numbered List
• Quote (blockquote)
• Code (codeBlock)
• Table (inserts a 3x3 table with a header row)

The TextNodeProps interface defines the data structure required to render a text node. It supports both plain text and structured Tiptap JSON content.

Properties

• id: string - A unique identifier for the node.
• type: string - The node type.
• data: object - The payload of the node, which can include:
  • text: string - Plain text content.
  • content: JSONContent - Tiptap-formatted JSON content.
  • generated: object - Contains text: string if the content was AI-generated.
  • model: string - The name of the model used to generate the text.
  • instructions: string - The instructions used to generate the text.
  • updatedAt: string - Timestamp of the last update.

Use getTextFromTextNodes to retrieve all text content from a collection of XYFlow nodes. It extracts both the original text from standard text nodes and the generated?.text from nodes marked as generated. The function returns an array of non-empty strings.

import { getTextFromTextNodes } from '@/lib/xyflow';
import type { Node } from '@xyflow/react';

const textContent = getTextFromTextNodes(nodes as Node[]);

The DropzoneEmptyState component displays a placeholder UI when no files are currently selected (when src is empty).

• If children are provided, they are rendered instead.
• If no children are provided, it renders an upload icon, a prompt (e.g., "Upload a file"), and an automatic caption based on the Dropzone configuration:
  • Lists accepted file types if accept is set.
  • Displays size constraints (e.g., "between 10 KB and 1 MB") if minSize and maxSize are set.
  • Displays minimum or maximum size limits if only one is provided.
• It must be used within a Dropzone component.

<Dropzone accept={{ 'image/*': ['.png'] }}>
  <DropzoneEmptyState />
</Dropzone>

The nodeTypes object serves as the central registry for all available node components used within the Tersa workflow canvas. It maps unique string identifiers to their corresponding React component implementations. This registry is used by the canvas engine to determine which component to render when a specific node type is instantiated in a workflow.

import { nodeTypes } from './components/nodes';

// nodeTypes contains:
// - 'image': ImageNode
// - 'text': TextNode
// - 'drop': DropNode
// - 'video': VideoNode

Use loadCanvas to retrieve the previously saved canvas state from localStorage. It looks for data stored under the key tersa-canvas.

• If data exists and is valid, it returns a CanvasData object containing nodes and edges.
• If no data is found, or if the stored data is corrupted/invalid, it returns null.

import { loadCanvas } from './lib/canvas-storage';
import type { CanvasData } from './lib/canvas-storage';

const savedData = loadCanvas();

if (savedData) {
  const { nodes, edges } = savedData;
  // Apply nodes and edges to your canvas
} else {
  // No saved state found
}