# How to Contribute to the Karakeep Project: A Complete Developer's Guide

> Learn how to contribute to the Karakeep project with this developer's guide. Discover how to clone, install dependencies, create endpoints, and submit PRs to join the karakeep-app/karakeep development.

- Repository: [Karakeep App/karakeep](https://github.com/karakeep-app/karakeep)
- Tags: how-to-guide
- Published: 2026-07-07

---

**Contribute to Karakeep by cloning the Turborepo monorepo, installing dependencies with `pnpm`, and following the standardized workflow of creating tRPC endpoints in `packages/trpc` and React components in `apps/web` before submitting tested, linted pull requests.**

Karakeep is a modern, self-hostable "read-it-later" platform that welcomes community contributions through its well-organized TypeScript monorepo. When you contribute to the Karakeep project, you'll work within a **Turborepo** architecture managed by `pnpm`, featuring Next.js frontends, Hono-based APIs, and background workers. This guide covers the repository structure, local development setup, and the exact workflow for submitting code that meets the project's quality standards.

## Understanding the Karakeep Monorepo Architecture

Karakeep organizes code into distinct layers within a single repository. Knowing this structure helps you locate the right place for your changes:

- **Frontend (`apps/web`)**: Next.js application using the App Router, Tailwind CSS, and shadcn/ui components located in `packages/web/components/ui`.
- **Backend API (`packages/api`, `packages/trpc`)**: Hono HTTP server with tRPC for type-safe client-server communication. New features typically add routes to `packages/trpc/routers/`.
- **Database (`packages/db`)**: Drizzle ORM managing PostgreSQL/SQLite with migration files.
- **Shared Code (`packages/shared`, `packages/shared-react`, `packages/shared-server`)**: Types, utilities, and React hooks used across client and server boundaries.
- **Workers (`apps/workers`)**: Background processes for link crawling, OCR, and video archiving.
- **CLI & Extensions (`apps/cli`, `apps/browser-extension`, `apps/mobile`, `apps/mcp`)**: Command-line tools, browser extensions, mobile apps, and MCP server implementations.
- **SDK (`packages/sdk`, `packages/open-api`)**: Generated SDKs and OpenAPI specifications for third-party integrations.

The project enforces code quality through **Vitest** for testing and **oxlint/oxfmt** for linting and formatting. Deployment configurations live in Docker and Kubernetes manifests at the repository root.

## Setting Up Your Local Development Environment

Before contributing to Karakeep, you need a working local instance. The project provides a Docker-based development stack for consistency.

First, clone the repository and install dependencies:

```bash
git clone https://github.com/karakeep-app/karakeep.git
cd karakeep
pnpm install

```

Next, initialize the development stack using the provided script:

```bash
./start-dev.sh

```

This command spins up PostgreSQL, Meilisearch, and the web application in development mode. For detailed environment configuration and database setup options, consult the official documentation at `docs.karakeep.app/Development/setup` and the [`AGENTS.md`](https://github.com/karakeep-app/karakeep/blob/main/AGENTS.md) file in the repository root.

Verify your setup by running the test suite:

```bash
pnpm test

```

## The Karakeep Contribution Workflow

Follow this structured workflow to ensure your contribution aligns with project standards:

1. **Select an Issue**: Choose from issues labeled `status/approved` on the GitHub tracker, or propose a new feature through GitHub Discussions.
2. **Claim and Discuss**: Comment on the issue to claim it and clarify requirements with maintainers.
3. **Review Guidelines**: Read [`CONTRIBUTING.md`](https://github.com/karakeep-app/karakeep/blob/main/CONTRIBUTING.md) at the repository root for specific rules on commit messages, branching, and PR descriptions.
4. **Implement Changes**: Write code following existing patterns—typically this means adding tRPC procedures in `packages/trpc/routers/` or React components in `apps/web/`.
5. **Add Tests**: Write Vitest unit tests following examples in `packages/trpc/routers/*.test.ts`.
6. **Lint and Format**: Run `pnpm lint:fix` and `pnpm format:fix` to apply automatic corrections using `oxlint` and `oxfmt`.
7. **Submit PR**: Push your branch and open a pull request. Include screenshots for UI changes and reference the original issue.

## Contributing Code: Adding a New tRPC Endpoint

Most Karakeep features expose functionality through tRPC routers. Here's how to add a health-check endpoint as an example:

Create the router file at [`packages/trpc/routers/health.ts`](https://github.com/karakeep-app/karakeep/blob/main/packages/trpc/routers/health.ts):

```typescript
import { publicProcedure, router } from '../index';

export const healthRouter = router({
  ping: publicProcedure
    .query(() => ({
      status: 'ok',
      timestamp: new Date().toISOString(),
    })),
});

```

Wire this router into the main application router in [`packages/trpc/index.ts`](https://github.com/karakeep-app/karakeep/blob/main/packages/trpc/index.ts) by adding `health: healthRouter` to the `appRouter` definition.

Add corresponding tests in [`packages/trpc/routers/health.test.ts`](https://github.com/karakeep-app/karakeep/blob/main/packages/trpc/routers/health.test.ts):

```typescript
import { createTRPCClient } from '@trpc/client';
import { appRouter } from '../index';

test('health ping returns ok', async () => {
  const client = createTRPCClient({ router: appRouter });
  const res = await client.health.ping.query();
  expect(res.status).toBe('ok');
});

```

Run the specific test file to verify your implementation:

```bash
pnpm test packages/trpc/routers/health.test.ts

```

## Key Files Every Contributor Should Know

Reference these files when navigating the codebase:

- **[`CONTRIBUTING.md`](https://github.com/karakeep-app/karakeep/blob/main/CONTRIBUTING.md)**: Official contribution guidelines covering issue handling and PR workflow.
- **[`AGENTS.md`](https://github.com/karakeep-app/karakeep/blob/main/AGENTS.md)**: Comprehensive architecture overview and package relationships.
- **[`packages/trpc/routers/users.ts`](https://github.com/karakeep-app/karakeep/blob/main/packages/trpc/routers/users.ts)**: Production example of a full-featured tRPC router with authentication and rate-limiting.
- **`apps/web/`**: Next.js application source code and page components.
- **`packages/db/`**: Drizzle ORM schema definitions and migration logic.
- **`apps/workers/`**: Background job processors for asset handling.
- **`.github/workflows/`**: CI/CD pipelines for continuous integration and Docker builds.

## Summary

- **Karakeep uses a Turborepo monorepo** with `pnpm` workspaces defined in [`pnpm-workspace.yaml`](https://github.com/karakeep-app/karakeep/blob/main/pnpm-workspace.yaml).
- **Local development requires Docker** via [`./start-dev.sh`](https://github.com/karakeep-app/karakeep/blob/main/./start-dev.sh) to run PostgreSQL and Meilisearch dependencies.
- **Most contributions involve tRPC routers** in `packages/trpc/routers/` or React components in `apps/web/`.
- **Code quality is enforced** through Vitest tests and oxlint/oxfmt formatting before PR submission.
- **Issues labeled `status/approved`** represent work ready for community contribution.

## Frequently Asked Questions

### Do I need to know TypeScript to contribute to Karakeep?

Yes, Karakeep is built entirely in TypeScript. Familiarity with React, Next.js, and tRPC patterns is essential for frontend and API contributions. However, documentation improvements or Docker configuration changes may require less TypeScript depth.

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

Execute `pnpm test` from the repository root to run the full Vitest suite. For faster feedback during development, run specific test files with `pnpm test packages/trpc/routers/[filename].test.ts`. Always ensure tests pass before committing, as CI will block PRs with failing checks.

### Where should I implement new API endpoints?

New endpoints belong in `packages/trpc/routers/` as tRPC procedures. Create a new router file or extend an existing one (like the [`users.ts`](https://github.com/karakeep-app/karakeep/blob/main/users.ts) example), then wire it into the main `appRouter` in [`packages/trpc/index.ts`](https://github.com/karakeep-app/karakeep/blob/main/packages/trpc/index.ts). This ensures type safety across the client-server boundary.

### Can I contribute to Karakeep without setting up the full Docker stack?

While [`./start-dev.sh`](https://github.com/karakeep-app/karakeep/blob/main/./start-dev.sh) provides the easiest path, you can run individual services manually if you provide your own PostgreSQL and Meilisearch instances. Set the appropriate environment variables in a `.env` file and run `pnpm dev` in specific apps, though the Docker method is recommended for consistency with production.