Development Guide

Setup and development workflow for Teak

Prerequisites: Git plus Bun and Node.js at the versions pinned in package.json (packageManager and engines.node). Setup validates both and refuses to run on the wrong toolchain.

Quick Start (local)

Clone the repository

git clone https://github.com/praveenjuge/teak.git

Move into the project

cd teak

Provision the local stack

bun run setup

Setup installs dependencies, provisions an isolated Convex development deployment, and derives the local env files. It needs no production credentials. For another surface, pass --target (see below).

Verify readiness

bun run doctor

Start the stack

bun run dev

The web app and documentation open in your default browser once both are ready.

Access Points

Web app: http://localhost:3000
Docs (proxies local /api and /mcp): http://localhost:3001
Mobile: Expo Go or a simulator; Safari extension: Xcode

See the repository README for the monorepo layout.

Core Commands

bun run setup            # First run: install deps + provision Convex + write local env
bun run setup --target desktop --convex local --json  # Per-target setup with a machine-readable report
bun run doctor           # Validate the environment (--json --target --profile for agents)
bun run dev              # Web + Convex backend (bun run dev --help for targets)
bun run dev web --headless  # Non-interactive output for agents and CI
bun run dev --all        # All services
bun run smoke:web        # End-to-end local session check (needs the stack running)
bun run audit:env        # Environment contract + local dotenv audit

bun run dev convex       # Convex backend only
bun run dev web          # Next.js web
bun run dev mobile       # Expo mobile
bun run dev desktop      # Electron desktop
bun run dev extension    # Chrome extension
open apps/safari-extension/teak-safari.xcodeproj # Safari extension
bun run dev raycast      # Raycast extension
bun run dev docs         # Docs site

bun run build            # Production build (all)
bun run build:extension  # Package Chrome extension
bun run build:raycast    # Build Raycast extension

bun run lint && bun run typecheck
bun run test             # Unit tests (turbo; test:unit / test:edge for Convex splits)
bun run verify           # typecheck + lint + test (affected)

bun run check            # Quality report (Ultracite)
bun run fix              # Auto-fix issues

bun run pre-commit       # Pre-commit checks
bun run publish:raycast  # Publish to Raycast store
bun run clean            # Clear Turborepo caches

Supported Targets and Limitations

bun run setup --target <name> provisions one surface. Every target except e2e works with zero copied credentials.

Target	Needs	Limitations
`web`	Convex deployment	None; the default path
`docs`, `cli`	Nothing beyond install	No Convex provisioning
`desktop`, `extension`	Convex deployment	Env files derive `VITE_*` aliases automatically
`mobile-simulator`	Convex deployment	iOS simulator uses loopback; Android emulators need `10.0.2.2` instead of `localhost`
`mobile-device`	Convex deployment, LAN	The host must be LAN-reachable; doctor reports the address or an actionable diagnostic
`files-worker`	`bun run sync:cloudflare-dev` afterwards	Worker secrets are owned by the sync command, not setup
`e2e`	Production credentials	Not provisioned by setup; see `packages/tests/README.md`

Linked git worktrees get deterministic ports and a namespace; pair them with --convex cloud for an isolated cloud development deployment so two checkouts never collide. iOS simulators, device builds, Xcode, and Safari stay on macOS.

Reporting Setup Problems

Paste the redacted JSON report with your issue. It contains check names and remediations but never secret values:

bun run doctor --target web --profile local --json

Setup Checklist

Convex + Better Auth

Follow the self-hosting quickstart for bun run setup, BETTER_AUTH_SECRET, and bunx convex dev — it provisions the same isolated Convex deployment local development uses. Google and Apple sign-in are optional locally: without their credentials, email sign-in works normally and the social buttons report that the provider isn’t configured.

Public API and MCP

The public REST API, MCP endpoint, discovery routes, OpenAPI spec, and SDK live in packages/convex. Start Convex to serve the HTTP routes, then use the docs dev proxy for local API and MCP URLs.

Example:

bun run dev:convex

The docs dev server proxies /api, /mcp, and OAuth protected-resource metadata to the Convex dev deployment. That gives local docs, examples, and smoke tests the same path shape as production: /api/v1 and /mcp.

Native OAuth clients revoke credentials with a form-encoded POST to /api/oauth/revoke and read the account with GET /api/oauth/userinfo on the Convex site origin; both accept OAuth tokens only, never API keys.

MCP Registry

The repo includes server.json for the MCP registry under the com.teakvault/mcp namespace. Publishing is manual because the namespace requires DNS verification for teakvault.com:

npm install -g mcp-publisher
mcp-publisher login dns
mcp-publisher publish

Follow the CLI prompt to add the DNS TXT record, then publish once verification passes.

Environment Variables

See Self-Hosting → Environment settings for every env var required across web, mobile, extension, and the Convex backend.

Optional local overrides: TEAK_DEV_APP_URL (default: http://localhost:3000), TEAK_DEV_API_URL (only needed when your Convex dev site differs from the repo default), TEAK_DEV_DOCS_URL (default: http://localhost:3001).