Kemma Local Development Setup Guide

This guide explains how to clone Kemma from GitHub and run it locally using Turborepo.

---

Prerequisites

Before you begin, ensure you have the following installed:

Tool	Version	Purpose
Node.js	20.0.0+	JavaScript runtime
npm	11.6.2+	Package manager
Python	3.13+	Backend runtime
uv	Latest	Fast Python package manager

Check Your Versions

node --version   # Should be v20.x or higher
npm --version    # Should be v11.x or higher
python --version # Should be 3.13+

---

Step 1: Install Turborepo (if needed)

Turbo is included as a dev dependency in the project, so it will be installed automatically with npm install. However, you can also install it globally for convenience:

Option A: Global Installation (Recommended for Development)

npm install -g turbo

Verify the installation:

turbo --version

Option B: Use npx (No Installation Required)

If you prefer not to install globally, you can run Turbo commands using npx:

npx turbo dev

💡 Note: The project's package.json scripts already wrap Turbo commands, so npm run dev will work without a global installation.

---

Step 2: Clone the Repository

git clone https://github.com/dhilsand/kemma.git
cd kemma

---

Step 3: Install Dependencies

Frontend Dependencies (via npm workspaces)

npm install

This installs dependencies for:

• Root workspace (including Turbo)
• apps/web-client (React + Vite frontend)
• apps/server (FastAPI backend Node dependencies, if any)

Backend Dependencies (Python)

cd apps/server
uv sync
cd ../..

💡 Don't have uv? Install it with: pip install uv or pipx install uv

---

Step 4: Run the Development Server

Run Everything (Frontend + Backend)

From the project root:

npm run dev

Or using Turbo directly:

turbo dev

This starts both servers in parallel:

• Frontend: http://localhost:5173
• Backend: http://localhost:8000
• API Docs: http://localhost:8000/docs

Run Individual Services

To run only the frontend:

turbo dev --filter=web-client

To run only the backend:

turbo dev --filter=server

---

Available Turbo Commands

Command	Description
npm run dev	Start all services in development mode
npm run build	Build all packages for production
npm run test	Run all test suites
npm run lint	Lint all packages
npm run format	Format all code with Prettier
npm run typecheck	Run TypeScript + Pyright type checking
npm run check	Run typecheck + lint + test (CI validation)
npm run clean	Clean all build artifacts

---

Troubleshooting

"turbo: command not found"

If you get this error, Turbo is not installed globally. You have two options:

1. Install globally: npm install -g turbo
2. Use npm scripts: Run npm run dev instead of turbo dev

Port Already in Use

If port 5173 or 8000 is busy:

# Kill the process using the port (example for port 5173)
lsof -ti:5173 | xargs kill -9

Python Dependencies Issues

Make sure you're using uv for Python dependency management:

pip install uv
cd apps/server
uv sync

---

Quick Start Summary

# 1. Clone
git clone https://github.com/dhilsand/kemma.git
cd kemma

# 2. Install dependencies
npm install
cd apps/server && uv sync && cd ../..

# 3. Run
npm run dev

🎉 That's it! Open http://localhost:5173 in your browser to see Kemma.

---

Resources

• Turborepo Documentation
• Kemma README
• Workspace Documentation