Development Guide

Setup and development workflow for Teak

Prerequisites: Bun 1.0+, Node.js 20+, Git

Quick Start (local)

Clone the repository

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

Move into the project

cd teak

Install dependencies

bun install

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://app.teak.localhost:1355
Public API: http://docs.teak.localhost:1355/api/v1
MCP Endpoint: http://docs.teak.localhost:1355/mcp
Convex Dashboard: opens after bunx convex dev
Mobile: Expo Go or simulator
Extension: Chrome dev mode
Safari Extension: Xcode
Docs: http://docs.teak.localhost:1355

Project Layout

teak/
- apps/
  - web/ Next.js frontend (app router, shadcn/ui)
  - mobile/ Expo React Native
  - desktop/ Electron desktop app (React)
  - extension/ Chrome extension (Wxt)
  - safari-extension/ Native macOS Safari extension app
  - raycast/ Raycast extension
  - cli/ npm command line client
  - docs/ Documentation site (Blume)
- packages/
  - convex/ Convex backend
    - ai/ AI metadata helpers
    - card/ Card mutations/queries
    - workflows/ AI pipeline orchestration
  - ui/ Shared UI components and hooks
- turbo.json Turborepo pipeline config
- package.json Root package + workspaces

Tech Stack

Layer	Technology
Backend	Convex (real-time DB + serverless)
Web	Next.js, React, TypeScript, TailwindCSS
Mobile	Expo React Native
Extensions	Wxt (Chrome), native Safari Web Extension (macOS)
Auth	Better Auth
UI	shadcn/ui + Radix
AI	Groq API
Billing	Polar
Testing	Bun (unit), Playwright (E2E)
Monorepo	Turborepo
Docs	Blume

Core Commands

bun run dev              # Web + Convex backend
bun run dev:all          # All services

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

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

Setup Checklist

Convex + Better Auth

Start a Convex dev deployment

bunx convex dev

Set the Better Auth signing secret

bunx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)

Point Convex at your local Next.js origin

bunx convex env set SITE_URL http://app.teak.localhost:1355

BETTER_AUTH_SECRET signs sessions (set once per environment). SITE_URL must match your Next.js origin. CONVEX_SITE_URL is the .site domain assigned by Convex—copy it from the dashboard.

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.

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://app.teak.localhost:1355), TEAK_DEV_API_URL (only needed when your Convex dev site differs from the repo default), TEAK_DEV_DOCS_URL (default: http://docs.teak.localhost:1355).