ape-im-sdk-react

React SDK for Ape Instant Messenger - Add nostalgic AOL-style chat functionality to your ApeChain dApp with a single line of code.

Features

• 💬 Popup Chat Widget - Floating chat bubble with full messenger interface
• 🔐 Wallet Authentication - Connect via MetaMask, WalletConnect, or any injected wallet
• 🎨 Retro AIM Aesthetic - Classic 90s AOL Instant Messenger design
• 🖼️ NFT Profile Pictures - Use your ApeChain NFTs as avatars
• 💰 Crypto Tipping - Send APE tokens directly in chat
• 🔒 Token-Gated Chats - Create exclusive group chats for token holders
• 📱 Real-time Messaging - WebSocket-powered instant delivery
• 🎭 Rich Content - Emoji reactions, GIFs, stickers, voice messages
• 🌙 Dark Mode - Full light/dark theme support

Installation

npm install ape-im-sdk-react
# or
yarn add ape-im-sdk-react
# or
pnpm add ape-im-sdk-react

Requirements

• React 18+
• Glyph Wallet - Ape IM requires Glyph for wallet authentication
• Ape IM API endpoint (defaults to https://www.apeinstantmessenger.com)

Quick Start

Add the chat widget to your app with just a few lines:

import { ApeIMProvider, ChatWidget } from 'ape-im-sdk-react';
import 'ape-im-sdk-react/styles.css';

function App() {
  return (
    <ApeIMProvider>
      <YourApp />
      <ChatWidget position="bottom-right" />
    </ApeIMProvider>
  );
}

That's it! Your users can now click the floating chat bubble to open the messenger.

Next.js / SSR Support

The ChatWidget component is fully SSR-compatible and will only render on the client. For Next.js apps, you can use it directly:

// pages/_app.tsx or app/layout.tsx
import { ApeIMProvider, ChatWidget } from 'ape-im-sdk-react';
import 'ape-im-sdk-react/styles.css';

function MyApp({ Component, pageProps }) {
  return (
    <ApeIMProvider>
      <Component {...pageProps} />
      <ChatWidget position="bottom-right" />
    </ApeIMProvider>
  );
}

The widget automatically handles server-side rendering by returning null during SSR and hydrating properly on the client.

Configuration

ApeIMProvider Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiUrl | string | https://www.apeinstantmessenger.com | API endpoint | | theme | 'light' \| 'dark' \| 'system' | 'system' | Color theme | | onConnect | (user: User) => void | - | Callback when user connects | | onDisconnect | () => void | - | Callback when user disconnects |

ChatWidget Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | 'bottom-right' \| 'bottom-left' | 'bottom-right' | Widget position | | offset | { x: number, y: number } | { x: 20, y: 20 } | Offset from corner | | defaultOpen | boolean | false | Start with widget open | | bubbleSize | number | 60 | Size of the chat bubble | | zIndex | number | 9999 | CSS z-index |

Hooks

useApeIM

Access authentication state and methods:

import { useApeIM } from 'ape-im-sdk-react';

function MyComponent() {
  const { 
    user,           // Current user object
    isConnected,    // Boolean connection state
    isLoading,      // Loading state
    connect,        // Connect wallet function
    disconnect,     // Disconnect function
    openWidget,     // Open the chat widget
    closeWidget,    // Close the chat widget
  } = useApeIM();

  return (
    <button onClick={connect}>
      {isConnected ? user.username : 'Connect'}
    </button>
  );
}

useConversations

Access user's conversations:

import { useConversations } from 'ape-im-sdk-react';

function ConversationList() {
  const { 
    conversations,  // Array of conversations
    isLoading,
    startConversation,  // Start new DM
    createGroup,        // Create group chat
  } = useConversations();

  return (
    <ul>
      {conversations.map(conv => (
        <li key={conv.id}>{conv.name}</li>
      ))}
    </ul>
  );
}

useChat

Access chat functionality for a specific conversation:

import { useChat } from 'ape-im-sdk-react';

function ChatRoom({ conversationId }) {
  const {
    messages,
    sendMessage,
    isTyping,
    participants,
  } = useChat(conversationId);

  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id}>{msg.content}</div>
      ))}
    </div>
  );
}

Styling

The SDK includes default retro AIM styling. Import the CSS:

import 'ape-im-sdk-react/styles.css';

Custom Theming

Override CSS variables to customize:

:root {
  --ape-im-primary: #1D3FE7;
  --ape-im-primary-dark: #142B99;
  --ape-im-accent: #E8EDFF;
  --ape-im-bubble-user: #1D3FE7;
  --ape-im-bubble-other: #e5e5e5;
}

TypeScript

Full TypeScript support with exported types:

import type { 
  User, 
  Message, 
  Conversation,
  ChatWidgetProps,
  ApeIMProviderProps,
} from 'ape-im-sdk-react';

API Documentation

For complete API documentation, visit: https://www.apeinstantmessenger.com/docs

Publishing to npm

To publish the SDK to npm:

# Navigate to the SDK package
cd packages/sdk-react

# Install dependencies
npm install

# Build the package
npm run build

# Login to npm (if not already)
npm login

# Publish to npm
npm publish --access public

Versioning

Before publishing a new version, update the version in package.json:

# Patch release (1.0.0 -> 1.0.1)
npm version patch

# Minor release (1.0.0 -> 1.1.0)
npm version minor

# Major release (1.0.0 -> 2.0.0)
npm version major

Development

# Install dependencies
npm install

# Build with watch mode for development
npm run dev

# Build for production
npm run build

License

MIT © Ape IM Team