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

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:

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

Next, initialize the development stack using the provided script:

./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 file in the repository root.

Verify your setup by running the test suite:

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

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 by adding health: healthRouter to the appRouter definition.

Add corresponding tests in packages/trpc/routers/health.test.ts:

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:

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

Key Files Every Contributor Should Know

Reference these files when navigating the codebase:

• CONTRIBUTING.md: Official contribution guidelines covering issue handling and PR workflow.
• AGENTS.md: Comprehensive architecture overview and package relationships.
• 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.
• Local development requires Docker via ./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 example), then wire it into the main appRouter in 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 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.

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