Skip to main content
This guide will help you set up Tarkov Kappa Navi for local development.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js >= 18
  • npm >= 9
  • Git for version control
We recommend using nvm to manage Node.js versions.

​
Getting Started

1

Fork the repository

Navigate to the TarkovKappaNavi repository and click the “Fork” button in the top right corner to create your own copy.
2

Clone your fork

Clone your forked repository to your local machine:
git clone https://github.com/YOUR_USERNAME/TarkovKappaNavi.git
cd TarkovKappaNavi
Replace YOUR_USERNAME with your GitHub username.
3

Add upstream remote

Add the original repository as an upstream remote to stay in sync:
git remote add upstream https://github.com/marlho/TarkovKappaNavi.git
4

Install dependencies

Install all project dependencies using npm:
npm install
5

Start the development server

Run the development server:
npm run dev
The application will be available at http://localhost:5173

​
Available Scripts

The project includes several npm scripts for development: 
npm run dev

​
Script Details

  • npm run dev - Starts Vite development server with hot module replacement
  • npm run build - Runs TypeScript type checking (tsc -b) followed by production build
  • npm run preview - Preview the production build locally
  • npm run lint - Run ESLint to check code quality
  • npm run test - Run all tests once using Vitest
  • npm run test:watch - Run tests in watch mode for active development
The build command includes TypeScript type checking, so you’ll see type errors during the build process if any exist.

​
Project Structure

Understanding the project structure will help you navigate the codebase: 
src/
├── api/           # GraphQL API communication, normalization, React Query hooks
├── components/    # UI components organized by feature
│   ├── dashboard/ # Dashboard screen components
│   ├── detail/    # Task detail panel components
│   ├── hideout/   # Hideout screen components
│   ├── items/     # Item screen components
│   ├── layout/    # AppShell, Header, Sidebar components
│   ├── map/       # Map screen components
│   ├── settings/  # Settings screen components
│   ├── share/     # QR code sharing components
│   ├── tasks/     # Task list screen components
│   └── ui/        # Reusable UI components
├── data/          # Static data files
├── db/            # Dexie database definitions and CRUD operations
├── domain/        # Domain logic (unlock checks, Kappa progress, filters, etc.)
├── hooks/         # Custom React hooks
├── i18n/          # Internationalization (Japanese/English)
├── lib/           # Utilities (QR sharing, pin presets, etc.)
└── stores/        # Zustand state stores

​
Architecture Overview

Tarkov Kappa Navi uses a client-side architecture:
  • API Data: Fetched from tarkov.dev GraphQL API, cached in memory with TanStack Query (12h TTL)
  • User Data: Persisted in IndexedDB using Dexie (profile, progress, notes, pins, etc.)
  • UI State: Managed with Zustand stores
  • Domain Logic: Pure functions for unlock detection, filtering, and recommendations

​
Technology Stack

CategoryTechnology
FrameworkReact 18 + TypeScript
Build ToolVite 7
State ManagementZustand v5
Server StateTanStack Query v5
Local DatabaseDexie v4 (IndexedDB)
ValidationZod v4
RoutingReact Router v7
StylingCSS Modules
TestingVitest
LintingESLint
IconsLucide React

​
Next Steps

Now that your environment is set up:
  1. Read the Contributing Guidelines to understand our coding standards
  2. Learn about our Testing Strategy
  3. Check the GitHub Issues for tasks to work on
This project is fully client-side with no backend required. All user data is stored locally in the browser’s IndexedDB.

Build docs developers (and LLMs) love

Get started for freeTalk to us