@becomeliminal/nim-chat

A React chat widget that connects to any nim SDK backend (Go, Python, etc).

Installation

npm install @becomeliminal/nim-chat

Quick Start

import { NimChat } from '@becomeliminal/nim-chat';
import '@becomeliminal/nim-chat/styles.css';

function App() {
  return (
    <NimChat
      wsUrl="ws://localhost:8080/ws"
      title="Nim"
      position="bottom-right"
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | wsUrl | string | required | WebSocket URL to connect to | | title | string | "Nim" | Header title in the chat panel | | position | "bottom-right" \| "bottom-left" | "bottom-right" | Widget position | | defaultOpen | boolean | false | Whether the panel starts open |

WebSocket Protocol

The widget implements the nim SDK WebSocket protocol:

Client → Server

| Type | Fields | Description | |------|--------|-------------| | new_conversation | - | Start a new conversation | | resume_conversation | conversationId | Resume existing conversation | | message | content | Send a user message | | confirm | actionId | Approve a pending action | | cancel | actionId | Cancel a pending action |

Server → Client

| Type | Fields | Description | |------|--------|-------------| | conversation_started | conversationId | New conversation created | | conversation_resumed | conversationId, messages[] | Conversation restored | | text_chunk | content | Streaming text chunk | | text | content | Complete message | | confirm_request | actionId, tool, summary, expiresAt | Action requires approval | | complete | tokenUsage? | Turn completed | | error | content | Error occurred |

Advanced Usage

Custom Implementation

You can use individual components and the hook for custom implementations:

import {
  ChatPanel,
  ChatMessage,
  ChatInput,
  ConfirmationCard,
  ThinkingIndicator,
  useNimWebSocket,
} from '@becomeliminal/nim-chat';
import '@becomeliminal/nim-chat/styles.css';

function CustomChat() {
  const {
    messages,
    isStreaming,
    connectionState,
    confirmationRequest,
    sendMessage,
    confirmAction,
    cancelAction,
  } = useNimWebSocket({
    wsUrl: 'ws://localhost:8080/ws',
    onError: (error) => console.error(error),
  });

  // Build your own UI...
}

Theme Tokens

Access design tokens for consistent styling:

import { theme, colors, typography, spacing } from '@becomeliminal/nim-chat';

// colors.orange = '#FF6D00'
// colors.cream = '#F1EDE7'
// etc.

Development

# Install dependencies
npm install

# Start dev server with example
npm run dev

# Build for production
npm run build

# Type check
npm run typecheck

Testing with nim-go-sdk

1. Start the nim-go-sdk example server:

   cd /path/to/nim-go-sdk/examples/basic
   ANTHROPIC_API_KEY=your-key go run main.go

2. Run the nim-chat example:

   cd nim-chat
   npm run dev

3. Open http://localhost:5173 and test:

   • Click bubble → panel opens
   • Send message → streaming response
   • Trigger tool → confirmation card appears
   • Approve/cancel → action executes or cancels
   • Refresh → conversation resumes from localStorage

Design System

Based on the Liminal mobile app design:

• Orange #FF6D00 - Primary, user bubbles, CTAs
• Cream #F1EDE7 - Background, assistant bubbles
• Blue #9BC1F3 - Focus states, interactive elements
• Black #231F18 - Primary text
• Brown #492610 - Secondary text
• Green #188A31 - Success, approval

License

MIT