49 lines
1.6 KiB
Markdown
49 lines
1.6 KiB
Markdown
# Toes - Claude Code Guide
|
|
|
|
## What It Is
|
|
Personal web server framework that auto-discovers and runs multiple web apps on your home network. "Set it up, turn it on, forget about the cloud."
|
|
|
|
## How It Works
|
|
1. Host server scans `/apps` directory for valid apps
|
|
2. Valid app = has `package.json` with `scripts.toes` entry
|
|
3. Each app spawned as child process with unique port (3001+)
|
|
4. Dashboard UI shows all running apps with links
|
|
|
|
## Key Files
|
|
- `src/server/apps.ts` - **The heart**: app discovery, process management, lifecycle
|
|
- `src/server/index.tsx` - Entry point (minimal, just initializes Hype)
|
|
- `src/pages/index.tsx` - Dashboard UI
|
|
- `apps/*/package.json` - Must have `"toes": "bun run --watch index.tsx"` script
|
|
- `TODO.md` - User-maintained task list (read this!)
|
|
|
|
## Tech Stack
|
|
- **Bun** runtime (not Node)
|
|
- **Hype** (custom HTTP framework wrapping Hono) from git+https://git.nose.space/defunkt/hype
|
|
- **Forge** (typed CSS-in-JS) from git+https://git.nose.space/defunkt/forge
|
|
- TypeScript + Hono JSX
|
|
|
|
## Running
|
|
```bash
|
|
bun run --hot src/server/index.tsx # Dev mode with hot reload
|
|
```
|
|
|
|
## App Structure
|
|
```tsx
|
|
// apps/example/index.tsx
|
|
import { Hype } from 'hype'
|
|
const app = new Hype()
|
|
app.get('/', c => c.html(<h1>Content</h1>))
|
|
export default app.defaults
|
|
```
|
|
|
|
## Conventions
|
|
- Apps get `PORT` env var from host
|
|
- Each app is isolated process with own dependencies
|
|
- No path-based routing - apps run on separate ports
|
|
- `DATA_DIR` env controls where apps are discovered
|
|
|
|
## Current State
|
|
- Core infrastructure: ✓ Complete (discovery, spawn, watch, ports, UI)
|
|
- Apps: basic, profile (working); risk, tictactoe (empty)
|
|
- Check TODO.md for planned features
|