MelonyProvider

The main provider component that manages chat state and handles server communication.

Overview

MelonyProvider is the root component that wraps your chat interface and provides context to all melony hooks. It manages the streaming chat state and handles communication with your server.

Basic Usage

import { MelonyProvider } from "melony";

function App() {
  return (
    <MelonyProvider endpoint="/api/chat">
      <YourChatComponent />
    </MelonyProvider>
  );
}

Props

endpoint

Type: string

Default: "/api/chat"

API endpoint for chat requests. Should return a streaming response in text/event-stream format.

headers

Type: Record<string, string>

Default: undefined

Additional headers to send with requests. Useful for authentication tokens or custom headers.

children

Type: React.ReactNode

React components that will have access to melony context and hooks.

TypeScript Generics

You can specify custom part types using TypeScript generics:

import { MelonyProvider } from "melony";

// Define your custom part type
type CustomPart = {
  melonyId: string;
  type: "text" | "image" | "tool_call";
  role: "user" | "assistant" | "system";
  text?: string;
  imageUrl?: string;
  toolName?: string;
  toolArgs?: Record<string, any>;
};

function App() {
  return (
    <MelonyProvider<CustomPart> endpoint="/api/chat">
      <YourChatComponent />
    </MelonyProvider>
  );
}

Examples

Basic setup

<MelonyProvider endpoint="/api/chat">
  <ChatInterface />
</MelonyProvider>

With custom headers

<MelonyProvider 
  endpoint="/api/chat"
  headers={{
    "Authorization": "Bearer your-token",
    "X-Custom-Header": "value"
  }}
>
  <ChatInterface />
</MelonyProvider>

With custom endpoint

<MelonyProvider endpoint="https://api.example.com/chat">
  <ChatInterface />
</MelonyProvider>

With custom types

type MyPart = {
  melonyId: string;
  type: "text" | "code" | "image";
  role: "user" | "assistant";
  text?: string;
  code?: string;
  language?: string;
  imageUrl?: string;
};

<MelonyProvider<MyPart> endpoint="/api/chat">
  <ChatInterface />
</MelonyProvider>

Context Value

The MelonyProvider provides the following context to child components:

endpoint

The API endpoint URL for chat requests.

headers

Additional headers to include with requests.

messages

Array of all messages in the conversation.

status

Current conversation status (idle, requested, streaming, error).

send

Function to send a new message to the chat.

Error Handling

The MelonyProvider handles errors gracefully and provides error state through hooks:

import { MelonyProvider, useMelonyStatus } from "melony";

function ChatWithErrorHandling() {
  const status = useMelonyStatus();

  return (
    <div>
      {status === "error" && (
        <div className="error-message">
          Something went wrong. Please try again.
        </div>
      )}
      {/* Your chat UI */}
    </div>
  );
}

function App() {
  return (
    <MelonyProvider endpoint="/api/chat">
      <ChatWithErrorHandling />
    </MelonyProvider>
  );
}

Performance Considerations

Single Provider

Use only one MelonyProvider per application to avoid duplicate state management.

Provider Placement

Place the MelonyProvider as high as possible in your component tree, but only around components that need chat functionality.

Memory Management

The provider automatically manages memory by limiting the number of messages kept in state.

Migration from Other Libraries

If you're migrating from other chat libraries, here are some common patterns:

From react-chatbot-kit

// Before
import Chatbot from 'react-chatbot-kit';

// After
import { MelonyProvider } from 'melony';

// Wrap your components
<MelonyProvider endpoint="/api/chat">
  <YourChatComponents />
</MelonyProvider>

From react-chat-widget

// Before
import { Widget } from 'react-chat-widget';

// After
import { MelonyProvider, useMelonyMessages, useMelonySend } from 'melony';

// Use hooks instead of widget props
function ChatWidget() {
  const messages = useMelonyMessages();
  const send = useMelonySend();
  // Your custom UI
}