1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
# Project Context: Bun React TweetDeck
## Overview
This project is a **TweetDeck-like Twitter client** built with **Bun** and **React 19**. It utilizes Bun's native server and bundler capabilities, bypassing the need for tools like Webpack or Vite. It features a column-based layout for viewing different Twitter feeds (For You, Following, Lists, etc.).
## Tech Stack
- **Runtime & Bundler:** [Bun](https://bun.com) (v1.3.1+)
- **Frontend:** React 19, `prosody-ui` (local lib), Lucide React (icons).
- **Backend:** `Bun.serve()` (Native Bun HTTP server).
- **Data Fetching:** Custom Twitter API wrapper (`src/lib/fetching/twitter-api.ts`) using cookie-based authentication.
- **State Persistence:** Custom `usePersistentState` hook.
## Architecture
The application is a **Hybrid SSR/SPA**:
1. **Server (`src/index.ts`):**
* Serves the static `index.html`.
* Provides API endpoints at `/api/twitter/*`.
* Handles Twitter API requests by proxying them with a user-provided cookie.
2. **Client (`src/frontend.tsx` -> `src/App.tsx`):**
* Bootstrapped via `src/index.html`.
* Manages the UI state (columns, decks).
* Communicates with the local `/api/twitter` endpoints.
## Key Directories
- `src/index.ts`: **Server Entry Point**. Defines API routes and serves static files.
- `src/frontend.tsx`: **Client Entry Point**. Hydrates the React app.
- `src/App.tsx`: Main application component.
- `src/components/`: UI components.
* `ColumnBoard.tsx`: Manages the grid/layout of columns.
* `ChatColumn.tsx` / `TimelineColumn.tsx`: Individual feed columns.
* `TweetCard.tsx`: Displays a single tweet.
- `src/lib/fetching/`: Backend logic for data fetching.
* `twitter-api.ts`: The core service communicating with Twitter.
- `twatter-cookies.ts`: (Likely) Contains logic or types related to the auth cookie structure.
## Development & Usage
### Prerequisites
- **Bun** must be installed.
### Commands
- **Install Dependencies:**
```bash
bun install
```
- **Start Development Server (Hot Reload):**
```bash
bun dev
```
*Access at `http://localhost:3010`*
- **Build for Production:**
```bash
bun build
```
*Outputs to `dist/`*
- **Start Production Server:**
```bash
bun start
```
### Conventions
- **Bun-First:** Always use `bun` commands (`bun install`, `bun test`, `bun run`). Do not use `npm` or `yarn`.
- **Styles:** CSS is imported directly into TSX files (e.g., `import './index.css'`).
- **Local Libs:** The project relies on local libraries (`sortug`, `prosody-ui`) linked via `file:` paths in `package.json`.
- **Auth:** Authentication is handled via a raw Twitter cookie string passed in API requests.
## Notes for AI Agents
- When adding new API routes, define them in `src/index.ts`.
- When modifying the UI, look for components in `src/components/` first.
- The project uses **React 19**, so use modern React patterns (Hooks, Functional Components).
- Ensure `bun-python` usage is checked if modifying Python integration files (`tests/python.ts`, `src/lib/fetching/python.ts`).
|
