Development Workflow for Kaneo: A Complete Guide to Contributing

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.

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

The monorepo structure declared in 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, copy the sample file and populate the required variables.

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 defines a unified development command that boots both applications in watch mode.

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 at the root. Run linting across the monorepo with:

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:

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

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:

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 which orchestrates PostgreSQL and Kaneo containers:

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.

Summary

• Kaneo uses a pnpm monorepo managed by 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) 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. This allows the root 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. 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 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.

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