Contribution Guide for Kaneo Developers: From Setup to Pull Request

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

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

Install all monorepo dependencies from the root directory:

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

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 file explicitly recommends communicating early to avoid duplicate work.

Branching Strategy

Create a feature or fix branch using clear prefixes:

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:

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:

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:

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:

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:

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

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