# Development Workflow for Kaneo: A Complete Guide to Contributing

> Understand the Kaneo development workflow in this guide. Learn to set up dependencies, configure .env, and run pnpm dev to start the API and web client with hot reloading.

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

---

**The Kaneo development workflow uses a pnpm monorepo structure where you install dependencies once, configure a shared `.env` file, and run `pnpm dev` to simultaneously start the API on port 1337 and the web client on port 5173 with hot reloading.**

Kaneo is an open-source project management platform built as a **pnpm monorepo** containing the API backend and React web client. The development workflow for Kaneo, as implemented in usekaneo/kaneo, centers on unified tooling that coordinates both applications through a single workspace configuration. Contributors follow strict patterns for code organization, quality assurance, and deployment to maintain consistency across the codebase.

## Repository Setup and Installation

Begin by cloning the repository and installing dependencies using pnpm, which is required to properly resolve the workspace packages defined in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml).

```bash
git clone https://github.com/usekaneo/kaneo.git
cd kaneo
pnpm install

```

The monorepo structure declared in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) includes the `apps/*` directories, ensuring that dependencies for both the API and web client are installed and linked correctly.

## Environment Configuration

Kaneo uses a single `.env` file at the repository root to configure both applications simultaneously. As documented in [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md), copy the sample file and populate the required variables.

```bash
cp .env.sample .env

```

Edit `.env` to include `KANEO_CLIENT_URL`, `KANEO_API_URL`, `AUTH_SECRET`, and `DATABASE_URL`. This shared configuration simplifies local development by ensuring both the API (`apps/api`) and the web client (`apps/web`) reference the same environment variables.

## Starting the Development Servers

The root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) defines a unified development command that boots both applications in watch mode.

```bash
pnpm dev

```

This simultaneously starts:

- The **API server** on port 1337 (Hono framework with hot reload)
- The **web client** on port 5173 (Vite-based React application)

Changes to either codebase trigger immediate reloading, enabling rapid iteration across the full stack.

## Code Organization and Patterns

### API Development in `apps/api/src`

The backend follows a controller pattern using the **Hono** framework. Route definitions reside in `apps/api/src/{feature}/controllers/` and are annotated with `hono-openapi` for automatic OpenAPI documentation generation. When adding features, create new controller files within the relevant feature directory and register them in the main application entry.

### Web Client Development in `apps/web/src`

The React frontend organizes code into three primary directories:

- `components/` – Reusable UI components
- `fetchers/` – Data fetching logic
- `hooks/` – TanStack Query hooks for state management

Place new features under `apps/web/src/` following this structure to maintain consistency with the existing codebase.

## Quality Assurance and Testing

### Linting and Formatting with Biome

The repository enforces code standards using **Biome**, configured in [`biome.json`](https://github.com/usekaneo/kaneo/blob/main/biome.json) at the root. Run linting across the monorepo with:

```bash
pnpm lint

```

Pre-commit hooks in `.husky/pre-commit` automatically execute Biome checks before allowing commits, preventing unformatted code from entering the repository.

### TypeScript Type Checking

Ensure type safety across the workspace by running:

```bash
pnpm typecheck

```

This command invokes the TypeScript compiler to validate both the API and web client codebases without emitting files.

### Testing Strategy

Kaneo employs **Vitest** for testing the API, as configured in [`apps/api/vitest.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vitest.config.ts). The workflow includes two test suites:

- **Unit tests**: Located in `tests/api/`, testing individual modules
- **Integration tests**: Located in `tests/api-integration/`, requiring a running PostgreSQL instance to validate database interactions and API endpoints

Execute the full test suite with:

```bash
pnpm test           # Unit tests

pnpm test:integration  # Integration tests (requires PostgreSQL)

```

## Production Builds and Deployment

### Building Docker Images

When ready to deploy, compile both applications using:

```bash
pnpm build

```

This produces optimized builds and Docker images tagged `ghcr.io/usekaneo/api` and `ghcr.io/usekaneo/web`.

### Deployment Options

For local production testing, use the provided [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) which orchestrates PostgreSQL and Kaneo containers:

```bash
docker compose -f compose.yml up -d

```

For Kubernetes environments, the `charts/kaneo/` directory contains a Helm chart with configurable values for production deployments, as documented in [`charts/kaneo/README.md`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/README.md).

## Summary

- Kaneo uses a **pnpm monorepo** managed by [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) to coordinate the API and web client.
- A **single `.env` file** at the root configures both applications, simplifying local setup.
- Run **`pnpm dev`** to start both the API (port 1337) and web client (port 5173) with hot reloading.
- Code follows specific patterns: **Hono controllers** in `apps/api/src` and **React components/fetchers/hooks** in `apps/web/src`.
- **Biome** handles linting and formatting, while **Vitest** manages unit and integration testing.
- Deploy using **Docker Compose** ([`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml)) for quick setups or the **Helm chart** (`charts/kaneo/`) for Kubernetes.

## Frequently Asked Questions

### What package manager does Kaneo require and why?

Kaneo requires **pnpm** because the repository is structured as a monorepo using workspaces defined in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml). This allows the root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) scripts to orchestrate commands across both `apps/api` and `apps/web` while maintaining efficient disk space usage through content-addressable storage.

### How do I run only the API or web client during development?

While `pnpm dev` starts both services, you can navigate to the specific application directory and run the individual development command. For the API, run `pnpm dev` from within `apps/api/`; for the web client, run it from `apps/web/`. However, the unified root command is recommended to ensure environment variables remain synchronized.

### What testing framework does Kaneo use for the API?

Kaneo uses **Vitest** for testing the API, as configured in [`apps/api/vitest.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vitest.config.ts). The setup supports unit tests in `tests/api/` and integration tests in `tests/api-integration/` that validate database interactions against a real PostgreSQL instance.

### Can I deploy Kaneo without using Docker?

While the repository emphasizes Docker for production deployments (providing [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) and Helm charts), you can deploy the built artifacts manually by running `pnpm build` and executing the compiled output from `apps/api` and `apps/web` on any Node.js-compatible server. Ensure PostgreSQL is accessible and environment variables are configured accordingly.