GitHub Setup

This guide covers getting the HowlAlert monorepo running locally for development — API, docs, and native app.

Prerequisites

• Bun for the API and docs apps
• Xcode 16+ for the native app (macOS only)
• Wrangler CLI for local API dev

1. Fork and clone

Fork the repository on GitHub, then clone your fork:

git clone https://github.com/<your-username>/howlalert.git
cd howlalert

Or clone the upstream directly if you're not planning to contribute:

git clone https://github.com/mrdemonwolf/howlalert.git
cd howlalert

2. Install dependencies

Each app manages its own dependencies — there are no workspace-level installs.

# API
cd apps/api && bun install
 
# Docs
cd apps/docs && bun install

The native app uses Swift Package Manager — dependencies are resolved automatically by Xcode or swift package resolve.

3. Local API development

Start a local Wrangler dev server (uses local KV and D1 stubs):

make worker-dev

Apply migrations to the local D1 stub:

make apply-migrations

The Worker is available at http://localhost:8787.

4. Local docs development

make docs-dev

The docs site is available at http://localhost:3000 with Turbopack hot reload.

5. Native builds

Open the Xcode project:

make open-xcode

Or build from the command line:

make build-mac    # macOS
make build-ios    # iOS Simulator
make build-watch  # watchOS Simulator
make build-all    # all three

6. Running tests

# Swift unit tests (HowlAlertKit SPM package only)
make test
 
# Full CI checks: API typecheck + docs build + swift test
make ci

API typecheck

cd apps/api && bun run typecheck

API lint

cd apps/api && bun run lint

Project structure

apps/
  api/       Cloudflare Worker (Hono + D1 + KV)
  docs/      Next.js 15 docs site (Fumadocs)
  native/    SwiftUI app (macOS / iOS / watchOS)

Run make help at the root for a full list of available targets.