# How to Contribute to Kaneo: A Complete Monorepo Guide

> Learn how to contribute to Kaneo a powerful monorepo. Follow our guide to fork the repo install dependencies and set up your local environment to start developing.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-05

---

**To contribute to Kaneo, fork the repository, install dependencies with `pnpm install`, configure your environment variables, and run `pnpm dev` to start both the API and web application locally.**

Kaneo is a **self-hosted project management platform** built as a pnpm monorepo with TurboRepo orchestration. Whether you're fixing bugs, adding features, or improving documentation, this guide walks you through the contribution workflow step by step based on the official source code at `github.com/usekaneo/kaneo`.

## Understanding Kaneo's Architecture

Before diving into code, grasp how the monorepo organizes responsibilities.

### Backend API (`apps/api`)

The backend is a **Hono server** written in TypeScript (Node 18+) that exposes OpenAPI-documented routes. It validates inputs with **Valibot** and persists data via **Drizzle ORM** to PostgreSQL【/cache/repos/github.com/usekaneo/kaneo/main/CLAUDE.md#L27-L31】.

### Frontend Web App (`apps/web`)

The frontend is a **React 19+ Vite application** using **TanStack Router** for file-based routing and **TanStack Query** for data fetching【/cache/repos/github.com/usekaneo/kaneo/main/CLAUDE.md#L38-L44】.

### Shared Packages (`packages/`, `charts/`)

Utilities, TypeScript configurations, and an optional MCP server live here, plus Helm charts for Kubernetes deployments【/cache/repos/github.com/usekaneo/kaneo/main/CLAUDE.md#L68-L75】.

## Step-by-Step: How to Contribute to Kaneo

### 1. Fork and Clone the Repository

Start by creating your own fork, then clone it locally.

```bash
git clone https://github.com/yourusername/kaneo.git
cd kaneo

```

### 2. Install Dependencies with pnpm

Kaneo uses **pnpm exclusively**. Do not use npm or yarn.

```bash
pnpm install

```

### 3. Configure Environment Variables

Create a `.env` file in the repository root. Required variables are documented in [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md)【/cache/repos/github.com/usekaneo/kaneo/main/ENVIRONMENT_SETUP.md#L24-L34】:

```bash
cp .env.sample .env

# Edit .env and set:

# - AUTH_SECRET

# - DATABASE_URL

# - Other required variables per ENVIRONMENT_SETUP.md

```

### 4. Start Development Servers

Run the following command to boot both services with hot-reloading【/cache/repos/github.com/usekaneo/kaneo/main/README.md#L41-L44】:

```bash
pnpm dev

```

- **API**: http://localhost:1337
- **Web app**: http://localhost:5173

### 5. Find or Create an Issue

Check for **"good first issue"** labels on GitHub, or discuss ideas on Discord before starting major work. This saves time and aligns your contribution with project goals.

### 6. Create a Feature Branch and Make Changes

```bash
git checkout -b feat/your-feature-name

# Edit files in apps/api/, apps/web/, or packages/

```

### 7. Run Tests Before Committing

Ensure your changes don't break existing functionality:

```bash
pnpm test              # Unit tests

pnpm test:integration  # API integration tests (requires PostgreSQL)

```

### 8. Commit Using Conventional Commits

Kaneo enforces **Conventional Commits** for changelog generation and release automation【/cache/repos/github.com/usekaneo/kaneo/main/CONTRIBUTING.md#L94-L108】:

```bash
git add .
git commit -m "feat: add board filtering by label"
git push origin feat/your-feature-name

```

**Valid prefixes**: `feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `test:`, `chore:`

### 9. Open a Pull Request

Submit your PR with:

- A clear description of the problem and solution
- References to related issues
- Screenshots for UI changes

CI pipelines will automatically lint, type-check, and build the entire monorepo before maintainers review.

## Code Quality Standards

### Biome Linting

All code must pass **Biome** linting and formatting. Run locally:

```bash
pnpm lint
pnpm format

```

### Internationalization (i18n)

UI contributions should follow the **i18next** workflow defined in [`CONTRIBUTING.md`](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md)【/cache/repos/github.com/usekaneo/kaneo/main/CONTRIBUTING.md#L94-L108】. Never hardcode user-facing strings.

## Key Files for Contributors

| File | Purpose |
|------|---------|
| [`CONTRIBUTING.md`](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md) | Full workflow, style guide, i18n requirements |
| [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) | Environment variables and troubleshooting |
| `apps/api/` | Backend routes, controllers, database schema |
| `apps/web/` | React components, hooks, TanStack routes |
| `packages/` | Shared utilities and configurations |
| `charts/kaneo/` | Helm chart for Kubernetes deployment |

## Summary

- **Fork and clone** the repository with your GitHub account
- **Use pnpm exclusively** — install with `pnpm install`
- **Configure `.env`** using [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) as reference
- **Run `pnpm dev`** to start API (port 1337) and web (port 5173)
- **Follow Conventional Commits** with `feat:`, `fix:`, etc.
- **Run tests** with `pnpm test` and `pnpm test:integration` before pushing
- **Respect Biome linting and i18n standards** defined in [`CONTRIBUTING.md`](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md)

## Frequently Asked Questions

### What Node.js version does Kaneo require?

Kaneo requires **Node.js 18 or higher** for the backend API and compatible versions for the frontend tooling. Check [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) engines fields if you encounter issues.

### Can I use npm or yarn instead of pnpm?

No. Kaneo is a **pnpm monorepo** with workspace-specific configurations. Using npm or yarn will break workspace linking and TurboRepo caching.

### How do I run integration tests locally?

Integration tests require a running **PostgreSQL** instance. Configure `DATABASE_URL` in your `.env` file, ensure the database is accessible, then run `pnpm test:integration`. The test suite will connect to your database and clean up test data after completion.

### Where should I put shared code between API and web?

Place shared utilities, types, or configurations in the `packages/` directory. The monorepo structure already includes packages for email utilities and TypeScript configs that both `apps/api` and `apps/web` depend on【/cache/repos/github.com/usekaneo/kaneo/main/CLAUDE.md#L68-L75】.