# Contribution Guide for Kaneo Developers: From Setup to Pull Request

> Kaneo contribution guide: setup Node 18+, pnpm, Git. Fork, install dependencies, configure env, and submit pull requests following Biome linting and Conventional Commits.

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

---

**The Kaneo contribution guide requires Node 18+, pnpm, and Git, followed by forking the repository, running `pnpm install`, configuring environment files, and submitting pull requests that pass Biome linting and Conventional Commit standards.**

The **Kaneo** project is an open-source task management platform built as a pnpm monorepo. Whether you are fixing a bug or adding a feature, following the official contribution workflow ensures your code integrates seamlessly with the existing **apps/api** and **apps/web** architecture.

## Prerequisites and Environment Setup

Before writing code, you must configure your local machine to match the project's runtime requirements.

### Required Tools

According to [`CONTRIBUTING.md`](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md) in the repository root, you need:
- **Node.js 18** or higher
- **pnpm** (package manager)
- **Git**
- **Docker** (optional, for running PostgreSQL locally)

### Repository Setup

Fork the **usekaneo/kaneo** repository on GitHub, then clone your fork locally:

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

```

Install all monorepo dependencies from the root directory:

```bash
pnpm install

```

### Environment Configuration

Both the API and web applications require environment variables to run. Create `.env` files in the appropriate directories by following the detailed specifications in **[`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md)**. This file lists every required variable, including `DATABASE_URL` and `AUTH_SECRET`, necessary for the API to connect to PostgreSQL and handle authentication.

## Development Workflow

Once dependencies are installed, you can start the development stack and begin coding.

### Starting the Development Servers

Run the following command from the repository root:

```bash
pnpm run dev

```

This concurrently starts the **API on port 1337** and the **web UI on port 5173** with hot-reload enabled. The API runs Hono with Drizzle ORM, while the web app serves the React frontend.

### Finding Issues to Work On

New contributors should look for issues labeled **"good first issue"** in the GitHub tracker. Alternatively, join the project's Discord channel to discuss potential features or claim open bugs. The [`CONTRIBUTING.md`](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md) file explicitly recommends communicating early to avoid duplicate work.

### Branching Strategy

Create a feature or fix branch using clear prefixes:

```bash
git checkout -b fix/description-of-bug

# or

git checkout -b feat/description-of-feature

```

This naming convention aligns with the Conventional Commits specification used throughout the project.

## Code Quality and Standards

Kaneo maintains strict quality gates to ensure codebase consistency.

### Linting and Formatting with Biome

The project uses **Biome** for both linting and code formatting. Before committing any changes, run:

```bash
pnpm run lint

```

This command auto-fixes style issues across the monorepo. The configuration is shared across `apps/api/`, `apps/web/`, and `packages/` to ensure uniform code style.

### Testing Requirements

Verify your changes do not break existing functionality by running the test suites:

```bash
pnpm test              # Unit tests

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

```

Integration tests validate the Hono API endpoints against a real database, ensuring database queries via Drizzle ORM function correctly.

### Conventional Commits

All commit messages must follow the **Conventional Commits** specification. Use these prefixes in your commit messages:

- `feat:` – New features
- `fix:` – Bug fixes
- `docs:` – Documentation changes
- `refactor:` – Code restructuring without feature changes
- `test:` – Test additions or corrections
- `chore:` – Maintenance tasks

Example:

```bash
git commit -m "fix: correct date picker overflow in task modal"

```

### Localization (i18n)

All user-facing strings must use **i18next** keys rather than hardcoded text. Translation files reside in the `i18n/` directory. Use the provided helper scripts to maintain synchronization:

```bash
pnpm i18n:check   # Verify all keys are translated

pnpm i18n:report  # Generate translation coverage reports

```

## Project Structure Overview

Understanding the monorepo layout helps you locate the correct location for new code:

- **`apps/api/`** – Backend API built with Hono and Drizzle ORM. Contains business logic, database schemas, and authentication handlers.
- **`apps/web/`** – Frontend React application. Houses UI components, custom hooks, and internationalization logic.
- **`apps/docs/`** – Documentation site.
- **`packages/`** – Shared utilities, TypeScript configurations, and common code used across applications.
- **`charts/kaneo/`** – Helm chart for Kubernetes deployments, useful for testing production-like environments.

## Submitting Your Contribution

After completing your changes and ensuring tests pass:

1. Push your branch to your fork:
   ```bash
   git push origin fix/description-of-bug
   ```

2. Open a Pull Request on the **usekaneo/kaneo** repository with a clear description of the problem and solution.

3. Reference any related issues and include screenshots for UI changes.

Community support is available via Discord, GitHub Issues, or GitHub Discussions if you encounter obstacles during the process.

## Summary

- **Prerequisites**: Node 18+, pnpm, Git, and optionally Docker for local PostgreSQL.
- **Setup**: Fork, clone, run `pnpm install`, and configure `.env` files per [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md).
- **Development**: Use `pnpm run dev` to start the API (port 1337) and web (port 5173).
- **Quality Gates**: Pass `pnpm run lint` (Biome), `pnpm test`, and `pnpm test:integration` before submitting.
- **Standards**: Use Conventional Commits (`feat:`, `fix:`) and i18next for all UI strings.
- **Structure**: Code belongs in `apps/api/` (backend), `apps/web/` (frontend), or `packages/` (shared).

## Frequently Asked Questions

### What Node.js version is required to contribute to Kaneo?

Kaneo requires **Node.js 18 or higher**. This is specified in [`CONTRIBUTING.md`](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md) to ensure compatibility with the pnpm workspace and modern JavaScript features used in the Hono and React applications.

### How do I run tests before submitting a pull request?

Run `pnpm test` for unit tests and `pnpm test:integration` for API integration tests. The integration tests require a running PostgreSQL instance and validate the Drizzle ORM queries and Hono endpoints. Both commands must pass before your PR can be merged.

### Where should I add new UI text or translations?

All user-facing text must be added to the **`i18n/`** directory using i18next keys. Never hardcode strings directly in components. Use the helper scripts `pnpm i18n:check` and `pnpm i18n:report` to ensure your translations are complete and synchronized across language files.

### What commit message format does Kaneo require?

Kaneo follows the **Conventional Commits** specification. Prefix your commit messages with `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, or `chore:` followed by a lowercase description. For example: `feat: add drag-and-drop task sorting`.