Skip to main content
Get your Teak development environment up and running with Bun, Node.js, and the required dependencies.

​
Prerequisites

Before you begin, ensure you have the following installed:
1

Install Bun

Teak uses Bun as its package manager and runtime. Install Bun 1.3.5 or later:
curl -fsSL https://bun.sh/install | bash
Verify installation:
bun --version
Teak is configured to use [email protected] as defined in package.json. The exact version will be enforced by the packageManager field.
2

Install Node.js

While Teak uses Bun, some dependencies require Node.js. Install Node.js 18 or later:
node --version  # Should be 18.0.0 or higher
3

Install Git

Version control is managed with Git:
  • Download from git-scm.com
  • Or install via package manager (Homebrew, apt, etc.)
git --version

​
Clone and Install

1

Clone the repository

git clone <repository-url>
cd teak
2

Install dependencies

Install all workspace dependencies using Bun:
bun install
This installs dependencies for all apps and packages in the monorepo, including:
  • Web app (Next.js)
  • Mobile app (Expo)
  • Desktop app (Tauri)
  • Browser extension (Wxt)
  • Convex backend
  • Documentation site
The prepare script will automatically run simple-git-hooks to set up pre-commit hooks.
3

Set up environment variables

Create environment files for your apps:
# Web app
cp apps/web/.env.example apps/web/.env.local

# Convex backend
cp packages/convex/.env.example packages/convex/.env
Configure required variables:
  • CONVEX_DEPLOYMENT - Your Convex deployment URL
  • NEXT_PUBLIC_CONVEX_URL - Public Convex URL for client-side
  • POLAR_ACCESS_TOKEN - Polar integration token (if using billing)
  • Other app-specific variables

​
Development Servers

Teak provides multiple development commands for different apps and services:

​
Primary Development

bun run dev
The default dev command starts:
  • Next.js web app at http://localhost:3000
  • Convex backend with hot reloading

​
Individual Services

bun run dev:web
Starts the Next.js web app and Convex backend:
  • Web: http://localhost:3000
  • Uses turbo watch for hot reloading
  • Automatically rebuilds on file changes

​
Building for Production

bun run build
The build process:
  1. Runs Turborepo build pipeline
  2. Builds dependencies in order (^build)
  3. Outputs to app-specific directories:
    • Web: .next/
    • Extension: dist/
    • Desktop: .output/

​
Code Quality

​
Linting and Type Checking

bun run lint

​
Testing

bun run test
Runs the test suite across all workspaces using Turborepo.

​
Pre-commit Hooks

The repository uses simple-git-hooks to run checks before commits: 
bun run pre-commit
This runs:
  • Type checking
  • Linting
  • Builds (only for affected packages)
Pre-commit hooks are automatically installed when you run bun install via the prepare script.

​
Workspace Management

Add dependencies to specific workspaces: 
bun add <package> --filter @teak/web
Examples: 
# Add React Query to web app
bun add @tanstack/react-query --filter @teak/web

# Add TypeScript types to Convex
bun add --dev @types/node --filter @teak/convex

​
Troubleshooting

​
Clear Cache

If you encounter issues, try clearing the Turbo cache: 
bun run clean
This command:
  • Stops the Turbo daemon
  • Clears node_modules/.cache
  • Removes all .turbo directories

​
Reinstall Dependencies

rm -rf node_modules
rm bun.lockb
bun install

​
Convex Issues

If Convex functions aren’t deploying:
  1. Check your deployment URL in .env
  2. Verify you’re authenticated: bunx convex dev
  3. Check Convex dashboard for errors
  4. Restart the dev server

​
Next Steps

Monorepo Structure

Learn about the Turborepo workspace structure

Convex Backend

Set up and develop with the Convex backend

Build docs developers (and LLMs) love

Get started for freeTalk to us