# Apps

An app is an HTTP server that runs on its assigned port.

## minimum requirements

```
apps/<name>/
  <timestamp>/        # YYYYMMDD-HHMMSS
    package.json
    index.tsx
  current -> <timestamp>  # symlink to active version
```

**package.json** must have `scripts.toes`:

```json
{
  "name": "my-app",
  "module": "index.tsx",
  "type": "module",
  "private": true,
  "scripts": {
    "toes": "bun run --watch index.tsx"
  },
  "toes": {
    "icon": "🎨"
  },
  "dependencies": {
    "@because/hype": "*",
    "@because/forge": "*"
  }
}
```

**index.tsx** must export `app.defaults`:

```tsx
import { Hype } from '@because/hype'

const app = new Hype()
app.get('/', c => c.html(<h1>Hello</h1>))

export default app.defaults
```

## environment

- `PORT` - your assigned port (3001-3100)
- `APPS_DIR` - path to `/apps` directory
- `DATA_DIR` - per-app data directory (`toes/<app-name>/`)

## health checks

Toes hits `GET /` every 30 seconds. Return 2xx or get restarted.

3 failures = restart with exponential backoff (1s, 2s, 4s, 8s, 16s, 32s).

## lifecycle

`invalid` -> `stopped` -> `starting` -> `running` -> `stopping`

Apps auto-restart on crash. `bun install` runs before every start.

## cli

```bash
toes new my-app          # create from template
toes list                # show apps
toes start my-app        # start
toes stop my-app         # stop
toes restart my-app      # restart
toes logs -f my-app      # tail logs
toes open my-app         # open in browser
```

## making a new app

```bash
toes new my-app --template=spa
```

- `ssr` - server-side rendered (default)
- `spa` - single page app (w/ hono/jsx)
- `bare` - minimal