dedalus-react

React hooks for building chat interfaces with Dedalus.

Installation

pnpm add dedalus-react dedalus-labs

Quick Start

Client (React)

import { useChat } from "dedalus-react";

function Chat() {
  const { messages, sendMessage, status, stop } = useChat({
    transport: { api: "/api/chat" },
  });

  return (
    <div>
      {messages.map((msg, i) => (
        <div key={i}>
          <strong>{msg.role}:</strong> {msg.content}
        </div>
      ))}

      <button onClick={() => sendMessage("Hello!")}>Send</button>

      {status === "streaming" && <button onClick={stop}>Stop</button>}
    </div>
  );
}

Server (Express)

Use streamToNodeResponse for Node.js HTTP frameworks like Express, Fastify, or the built-in http module.

import express from "express";
import Dedalus, { DedalusRunner } from "dedalus-labs";
import { streamToNodeResponse } from "dedalus-react/server";

const app = express();
const client = new Dedalus();
const runner = new DedalusRunner(client);

app.post("/api/chat", async (req, res) => {
  const { messages } = req.body;

  const stream = await runner.run({
    messages,
    model: "openai/gpt-4o-mini",
    stream: true,
  });

  await streamToNodeResponse(stream, res);
});

Server (Next.js App Router)

Use streamToWebResponse for environments using the Web Fetch API, including Next.js App Router, Cloudflare Workers, Deno, and Bun.

import Dedalus, { DedalusRunner } from "dedalus-labs";
import { streamToWebResponse } from "dedalus-react/server";

const client = new Dedalus();
const runner = new DedalusRunner(client);

export async function POST(req: Request) {
  const { messages } = await req.json();

  const stream = await runner.run({
    messages,
    model: "openai/gpt-4o-mini",
    stream: true,
  });

  return streamToWebResponse(stream);
}

API

useChat(options) Params

| Option | Type | Description | | --- | --- | --- | | transport | TransportConfig | Required. Transport configuration (see below) | | id | string | Chat session ID | | messages | Message[] | Initial messages | | generateId | () => string | Custom ID generator (defaults to crypto.randomUUID) | | onError | (error: Error) => void | Error callback | | onFinish | (opts: OnFinishOptions) => void | Completion callback | | onToolCall | (opts: OnToolCallOptions) => void \| Promise<void> | Tool call callback | | sendAutomaticallyWhen | (opts) => boolean \| Promise<boolean> | Auto-send condition for agentic flows |

Returns

| Property | Type | Description | | --- | --- | --- | | id | string | Chat session ID | | messages | Message[] | Current messages | | status | string | ready, submitted, streaming, or error | | error | Error \| undefined | Current error (if any) | | sendMessage | (message: Message \| string, options?: ChatRequestOptions) => Promise<void> | Send a message | | setMessages | (messages: Message[] \| (prev: Message[]) => Message[]) => void | Update messages | | stop | () => void | Stop streaming | | addToolResult | (opts: AddToolResultOptions) => void | Add a tool result to the conversation |

TransportConfig

| Property | Type | Description | | --- | --- | --- | | api | string \| () => string | Required. API endpoint | | headers | object \| Headers \| () => object | Additional request headers | | credentials | RequestCredentials \| () => RequestCredentials | Fetch credentials mode | | body | object \| () => object | Additional body properties merged into requests | | fetch | typeof fetch | Custom fetch function | | prepareRequestBody | (opts) => object | Transform the request body before sending |

OnFinishOptions

| Property | Type | Description | | --- | --- | --- | | message | Message | The final assistant message | | messages | Message[] | All messages in the conversation including the final assistant message | | isAbort | boolean | True if the request was aborted by the user | | isDisconnect | boolean | True if a network error caused disconnection | | isError | boolean | True if an error occurred during streaming |

OnToolCallOptions

| Property | Type | Description | | --- | --- | --- | | toolCall | ToolCall | The tool call received from the assistant |

ToolCall

| Property | Type | Description | | --- | --- | --- | | id | string | Unique identifier for this tool call | | type | "function" | The type of tool call | | function | { name: string; arguments: string } | The function name and JSON-encoded arguments |

SendAutomaticallyWhenOptions

| Property | Type | Description | | --- | --- | --- | | messages | Message[] | Current messages in the conversation |

Examples

The example/ directory contains working examples for different setups:

| Example | Description | | ------- | ----------- | | next-simple | Minimal Next.js App Router example | | next-model-select | Next.js with dynamic model selection | | react-express-simple | Minimal React + Express example | | react-express-model-select | React + Express with model selection |

Running an Example

cd example/next-simple  # or any other example
pnpm install
cp .env.example .env.local  # use .env for Express examples
# Add your DEDALUS_API_KEY to the env file
pnpm dev  # or pnpm start for Express examples

License

MIT