---
applyTo: "**"
excludeAgent: "code-review"
---

# Termux Development Setup

**You can develop CULTSCALE in Termux on Android.** This guide covers platform-specific caveats and workarounds.

**Check if you're in Termux:** `echo $PREFIX` should output `/data/data/com.termux/files/usr`

## Overview

Termux runs on ARM64 architecture, which requires special handling for some Node.js packages. This guide documents all known issues and solutions.

## System Requirements

- Termux (latest version)
- Node.js 24+
- npm
- Git with Git LFS
- Storage access configured

## Core Dependencies

### Install Base Packages

```bash
pkg update
pkg install git git-lfs nodejs python
```

### Configure Git LFS

```bash
git lfs install
```

## Project-Specific Setup

### 1. Sharp (Image Processing)

Sharp requires native compilation with libvips. The pre-built binaries don't support Android ARM64.

```bash
# Install libvips
pkg install libvips

# Rebuild Sharp for Termux
cd /data/data/com.termux/files/home/workspaces/cultscale
npm rebuild sharp
```

**Why needed:** Used by Astro for optimizing images during build.

### 2. Wrangler (Cloudflare CLI)

Wrangler includes `workerd` (Cloudflare Workers runtime) which doesn't support Android ARM64. We only need the API/admin commands for Pages deployment, so we can stub out the runtime.

```bash
# Install without postinstall scripts (skips workerd binary download)
npm install -g wrangler@latest --ignore-scripts

# Create stub for workerd module
tmpdir="${TMPDIR:-/tmp}"
cat > "$tmpdir/workerd-stub.js" << 'EOF'
module.exports = { binPath: '/dev/null' };
EOF

# Replace workerd main.js with stub
cp "$tmpdir/workerd-stub.js" \
  /data/data/com.termux/files/usr/lib/node_modules/wrangler/node_modules/workerd/lib/main.js
```

**Test it works:**
```bash
wrangler --version
wrangler whoami
```

**What works:**
- `wrangler whoami` - Check authentication
- `wrangler pages project list` - List Pages projects
- `wrangler pages deploy` - Deploy to Pages
- All API/admin commands

**What doesn't work:**
- `wrangler dev` - Local Workers development (requires workerd runtime)
- Workers-specific local testing

**Why this works:** Wrangler's API commands are pure Node.js HTTP requests to Cloudflare's API. Only local Workers dev requires the native `workerd` binary.

### 3. ImageMagick & Image Tools

Required for asset builds (favicon generation, image conversion):

```bash
pkg install imagemagick
pkg install librsvg  # For rsvg-convert
```

**Optional (if available):**
```bash
pkg install inkscape  # May not be available on all architectures
```

If Inkscape isn't available, the Makefile will use rsvg-convert as fallback.

## Termux-Specific Code Patterns

### Temporary Files

**Always use TMPDIR environment variable:**
```bash
# ✅ Correct
tmpdir="${TMPDIR:-/tmp}"
mkdir -p "$tmpdir/myapp"

# ❌ Wrong
mkdir -p /tmp/myapp
```

**Why:** Termux uses a different temp directory path. Hardcoding `/tmp` may fail or use restricted locations.

### File Permissions

Termux runs in Android's app sandbox with restricted permissions:
- `/tmp` may not be writable
- Use `$TMPDIR` or `$HOME` for temp files
- No system-wide installations outside Termux's prefix

## Common Issues & Solutions

### Issue: `npm rebuild sharp` fails

**Solution:**
```bash
pkg update
pkg install libvips
npm rebuild sharp --verbose
```

### Issue: Wrangler says "Unsupported platform"

**Solution:** Apply the workerd stub workaround above. Never try to install workerd directly.

### Issue: Permission denied writing to `/tmp`

**Solution:** Use `tmpdir="${TMPDIR:-/tmp}"` pattern and write to `$tmpdir` instead.

### Issue: Git LFS files not downloading

**Solution:**
```bash
git lfs install
git lfs pull
```

## Testing Your Setup

After setup, verify everything works:

```bash
# Test Node.js
node --version

# Test Wrangler
wrangler --version
wrangler whoami

# Test Sharp (build the site)
cd /data/data/com.termux/files/home/workspaces/cultscale
npm run build

# Test Image Tools
convert --version
rsvg-convert --version

# Test Git LFS
git lfs env
```

## Upgrading Wrangler

When updating Wrangler, reapply the workerd stub:

```bash
# Upgrade
npm install -g wrangler@latest --ignore-scripts

# Reapply stub
tmpdir="${TMPDIR:-/tmp}"
cat > "$tmpdir/workerd-stub.js" << 'EOF'
module.exports = { binPath: '/dev/null' };
EOF
cp "$tmpdir/workerd-stub.js" \
  /data/data/com.termux/files/usr/lib/node_modules/wrangler/node_modules/workerd/lib/main.js
```

## Additional Resources

- [Termux Wiki](https://wiki.termux.com/)
- [c0decafe/copilot-termux-setup](https://github.com/c0decafe/copilot-termux-setup) - General Termux + Copilot setup
- [Wrangler Documentation](https://developers.cloudflare.com/workers/wrangler/)

## Platform Detection

If you need to detect Termux in scripts:

```bash
if [ -n "$TERMUX_VERSION" ]; then
    echo "Running in Termux"
    # Termux-specific code
fi
```

Or in Node.js:
```javascript
const isTermux = process.env.TERMUX_VERSION !== undefined;
```