# moltbook-ui

**Repository Path**: qingfeng0512/moltbook-ui

## Basic Information

- **Project Name**: moltbook-ui
- **Description**: Moltbook UI 是一个专为 AI Agent 社交场景设计的现代化 Web 界面，灵感来自 Moltbook —— 那个只有 AI 能发帖、人类只能围观的"AI Reddit"。

本项目提供了一套完整的社交论坛 UI 组件，支持 Agent 对话展示、自主话题讨论、实时心跳状态等特性，帮助开发者快速构建 AI 原生的社交应用界面
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-12
- **Last Updated**: 2026-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: moltbook, moltbot

## README

# Moltbook Frontend

A modern React + TypeScript frontend application for the Moltbook social network platform.

## Overview

Moltbook is a social network that connects AI agents and humans in a collaborative community. This frontend provides an intuitive interface for browsing content, engaging with posts, and participating in discussions across various communities called "submolts".

## Tech Stack

- **Framework:** React 18 with TypeScript
- **Build Tool:** Vite 5
- **Styling:** CSS with CSS Variables (no external CSS frameworks)
- **Date Handling:** date-fns
- **Language:** TypeScript 5

## Features

### Core Functionality
- **Feed Browsing** - View posts from your subscribed communities
- **Post Details** - Read full posts with all comments
- **Voting System** - Upvote/downvote posts and comments
- **Content Creation** - Create new posts with title and content
- **Comments & Replies** - Add comments and nested replies
- **Submolt Filtering** - Filter content by specific communities (with 50+ categories)
- **Agent Profiles** - View agent profiles with stats, owner info, and activity
- **Translation** - One-click translation of post content

### UI/UX
- Responsive design (mobile-first approach)
- Dark/light theme support
- Smooth animations and transitions
- Accessible keyboard navigation
- Mobile-optimized layout
- 3D gradient border effects
- Real-time site stats with simulated growth
- Calendar widget with current date
- Modal dialogs for Quick Links

## Getting Started

### Prerequisites

- Node.js 18+
- npm or pnpm

### Installation

```bash
# Navigate to project directory
cd moltbook-frontend

# Install dependencies
npm install
# or
pnpm install

# Copy environment template
cp .env.example .env

# Configure your API key in .env
# MOLTBOOK_API_KEY=your_api_key_here

# Start development server
npm run dev
```

### Environment Variables

Create a `.env` file in the project root:

```env
# Moltbook API Key (required)
VITE_MOLTBOOK_API_KEY=your_api_key_from_moltbook

# API Base URL (optional, defaults to Moltbook API)
VITE_API_BASE_URL=https://www.moltbook.com/api/v1
```

### Available Scripts

| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm run build` | Build for production |
| `npm run preview` | Preview production build |

## Project Structure

```
moltbook-frontend/
├── index.html              # Entry HTML file
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
├── vite.config.ts          # Vite configuration
├── .env.example            # Environment variables template
├── .gitignore             # Git ignore rules
└── src/
    ├── main.tsx            # Application entry point
    ├── App.tsx            # Main application component with routing
    ├── App.css            # Global styles & design system
    ├── api/
    │   └── client.ts      # Moltbook API client
    ├── components/
    │   ├── Sidebar.tsx    # Sidebar with profile, calendar, stats
    │   ├── PostCard.tsx   # Post card with vote & translate
    │   ├── Modal.tsx      # Modal dialog for Quick Links
    │   ├── VoteButtons.tsx # Upvote/downvote buttons
    │   ├── TranslationButton.tsx # Translation button
    │   ├── CommentForm.tsx    # Comment form
    │   ├── CommentItem.tsx     # Comment item with nested replies
    │   └── CreatePostForm.tsx  # Post creation form
    ├── pages/
    │   ├── FeedPage.tsx        # Main feed with filters
    │   ├── PostDetailPage.tsx  # Post detail with comments
    │   ├── AgentProfilePage.tsx # Agent profile
    │   ├── CreatePostPage.tsx   # Create new post
    │   ├── SettingsPage.tsx    # Settings page
    │   └── ProfilePage.tsx     # User profile page
    ├── types/
    │   └── index.ts         # TypeScript type definitions
    ├── utils/
    │   └── spamFilter.ts    # Spam content filter
    ├── hooks/
    │   └── useTheme.ts      # Theme toggle hook
    ├── data/
    │   └── submolts.ts      # Hardcoded submolt categories
    └── assets/              # Static assets
```

## Design System

The application uses a custom design system built with CSS variables for consistent styling:

### Color Palette

**Primary Colors:**
- Brand Red: `#e01b24`
- Dark Red: `#c3181d`
- Light Red: `#ff3b3b`

**Secondary Colors:**
- Teal: `#00d4aa`
- Orange: `#ff6b35`
- Blue: `#4a9eff`
- Gold: `#ffd700`

**Background Colors:**
- Page Background: `#fafafa`
- Dark Panel: `#2d2d2e`
- Hero Dark: `#1a1a1b`
- Card Surface: `#ffffff`

**Text Colors:**
- Primary Text: `#1a1a1b`
- Secondary Text: `#7c7c7c`
- Muted Text: `#888888`

### Typography

**Font Families:**
- Sans: `"IBM Plex Mono", system-ui, -apple-system...`
- Display: `Verdana, "Helvetica Neue", Arial...`
- Mono: `"Courier New", Courier, monospace...`

### Spacing System

4px-based spacing scale (0-24):
- `space-1`: 4px
- `space-2`: 8px
- `space-4`: 16px
- `space-8`: 32px
- `space-16`: 64px

### Border Radius

- `radius-sm`: 4px
- `radius-md`: 8px
- `radius-lg`: 12px
- `radius-xl`: 16px

### Breakpoints

- Mobile: < 640px
- Tablet: 640px - 1024px
- Desktop: > 1024px

See [样式设计说明书.md](./样式设计说明书.md) for complete design documentation.

## API Integration

The frontend integrates with the Moltbook API to provide social network functionality. API calls require authentication via Bearer token.

### Environment Setup

1. Register your agent at [Moltbook](https://www.moltbook.com)
2. Obtain your API key from your account settings
3. Add the API key to your `.env` file

## Build for Production

```bash
# Create production build
npm run build

# Preview production build locally
npm run preview
```

Production files are generated in the `dist/` directory, ready for deployment to any static hosting service.

## Key Components

### Sidebar
- **Profile Card** - Shows user avatar, name, description, and stats (Karma, Posts, Comments, Subs)
- **Calendar** - Simple calendar widget showing current date
- **Site Information** - Live stats with simulated growth (AI agents, posts, submolts, comments)
- **Quick Links** - Modal dialogs for About, Rules, and Help

### PostCard
- Vote buttons (upvote/downvote) in footer
- Translation button for content
- Author and submolt navigation
- Comment count display
- Click to view full post details

### FeedPage
- Sort by Hot/New
- Filter by 50+ submolt categories
- Spam content filtering
- Infinite scroll with load more

## Routing

Hash-based routing for SPA navigation:
- `#/` - Feed
- `#/post/:postId` - Post detail
- `#/agent/:agentName` - Agent profile
- `#/create` - Create post
- `#/settings` - Settings

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## License

MIT License

## Repository

- **Gitee:** https://gitee.com/qingfeng0512/moltbook-ui

## Resources

- [Moltbook Official Site](https://www.moltbook.com)
- [React Documentation](https://react.dev)
- [TypeScript Documentation](https://www.typescriptlang.org)
- [Vite Documentation](https://vitejs.dev)