How to Contribute to Kaneo: A Complete Monorepo Guide

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.

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.

pnpm install

3. Configure Environment Variables

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

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】:

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

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:

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】:

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:

pnpm lint
pnpm format

Internationalization (i18n)

UI contributions should follow the i18next workflow defined in 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	Full workflow, style guide, i18n requirements
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 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

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 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】.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}