TREK/wiki/Development-environment.md

Developer Setup Guide

Before anything else, please read the Contributing guidelines.

Prerequisites

• Node.js 22+
• npm
• Git
• A GitHub account

---

1. Fork & Clone the Repository

Go to the TREK repository and click Fork to create your own copy.

Then clone your fork locally:

# Clone your fork, checking out the dev branch
git clone -b dev git@github.com:your-username/TREK.git
cd TREK

---

2. Configure Git Remotes

Add the original repository as upstream so you can pull in future updates:

git remote add upstream git@github.com:mauriceboe/TREK.git

You should now have two remotes:

Remote	URL	Purpose
origin	git@github.com:your-username/TREK.git	Your fork — push changes here
upstream	git@github.com:mauriceboe/TREK.git	Main repo — pull updates from here

---

3. Keep Your Fork Up to Date

Before starting any work, make sure your local dev branch is in sync with upstream:

git fetch upstream
git rebase upstream/dev  # or: git merge upstream/dev

---

4. Create a Feature Branch

Working on a dedicated branch keeps your changes isolated and makes PRs easier to review:

# Create a new branch off of dev
git checkout -b fix/my-changes origin/dev

Branch naming conventions:

• feat/short-description for new features
• fix/short-description for bug fixes
• chore/short-description for maintenance tasks

---

5. Install Dependencies

The repo is an npm workspace monorepo. One command at the root installs everything:

npm ci

---

6. Optional: KItinerary (Booking Import)

The booking-confirmation import feature uses KDE KItinerary to parse travel documents. The server works without it, but the import endpoint will be non-functional.

Linux — amd64

Download the static binary from the KDE CDN and verify the checksum:

wget -qO /tmp/ki.tgz https://cdn.kde.org/ci-builds/pim/kitinerary/release-26.04/linux/kitinerary-extractor-x86_64-26.04.0.tgz
echo "b7058d98990053c7b61847fef0c21e02d59b60e323e2b171ca210b682334e801  /tmp/ki.tgz" | sha256sum -c
sudo tar -xz -C /usr/local -f /tmp/ki.tgz bin/kitinerary-extractor share/locale
rm /tmp/ki.tgz

Linux — arm64

sudo apt-get install -y libkitinerary-bin
sudo ln -sf "$(find /usr/lib -name kitinerary-extractor -type f | head -1)" /usr/local/bin/kitinerary-extractor

Environment variables

Add these to your local .env (or export them before starting the server):

# Required: path to the extractor binary
KITINERARY_EXTRACTOR_PATH=/usr/local/bin/kitinerary-extractor

# Prevent Qt from probing for a display in headless/server environments
QT_QPA_PLATFORM=offscreen

# KDE cache directory (avoids writing to $HOME)
XDG_CACHE_HOME=/tmp/kf6-cache

You can override KITINERARY_EXTRACTOR_PATH if you installed the binary to a different location.

---

7. Available Scripts

Root (/)

These commands run across all workspaces at once and are the recommended way to work:

Command	Description
npm run dev	Build shared, then start shared (watch), server, and client together via concurrently
npm run build	Build shared → server → client in order
npm test	Run tests in shared, server, and client
npm run test:cov	Run coverage for server and client
npm run test:e2e	Run end-to-end tests (server)
npm run lint	Lint shared, server, and client
npm run format	Format shared, server, and client
npm run format:check	Check formatting across all workspaces

Shared (/shared)

The @trek/shared package is the single source of truth for code shared between the client and server. It holds the Zod schemas that define the API contracts (request/response shapes, common primitives, pagination) and the i18n translation layer (per-language keys and types). Both workspaces import from it, so schema and translation changes propagate to both sides from one place.

Tip: run npm run i18n:parity (or i18n:parity:strict) in this package to verify every locale exposes the same translation keys — the CI parity gate runs the strict variant.

Command	Description
npm run build	Compile shared package (tsup)
npm run build:watch	Compile in watch mode
npm test	Run tests
npm run typecheck	Type-check without emitting
npm run i18n:parity	Check locale key parity
npm run i18n:parity:strict	Strict locale key parity (CI gate)
npm run lint	Lint source
npm run format	Format source

Root (/)

These commands run across all workspaces at once and are the recommended way to work:

Command	Description
npm run dev	Build shared, then start shared (watch), server, and client together via concurrently
npm run build	Build shared → server → client in order
npm test	Run tests in shared, server, and client
npm run test:cov	Run coverage for server and client
npm run test:e2e	Run end-to-end tests (server)
npm run lint	Lint shared, server, and client
npm run format	Format shared, server, and client
npm run format:check	Check formatting across all workspaces

Shared (/shared)

The @trek/shared package is the single source of truth for code shared between the client and server. It currently holds Zod schemas that define API contracts (request/response shapes, common primitives, pagination). Both workspaces import from it so schema changes automatically propagate to both sides.

Upcoming: the i18n translation layer will be migrated into this package so that translation keys and types are enforced across the stack from one place.

Command	Description
npm run build	Compile shared package (tsup)
npm run build:watch	Compile in watch mode
npm test	Run tests
npm run typecheck	Type-check without emitting
npm run lint	Lint source
npm run format	Format source

Server (/server)

Command	Description
npm start	Start the server (production)
npm run dev	Start the server in watch mode
npm run build	Compile server
npm run typecheck	Type-check without emitting
npm test	Run all tests
npm run test:unit	Run unit tests only
npm run test:integration	Run integration tests
npm run test:ws	Run WebSocket tests
npm run test:e2e	Run end-to-end tests
npm run test:watch	Run tests in watch mode
npm run test:coverage	Run tests with coverage report
npm run lint	Lint source
npm run format	Format source

Client (/client)

Command	Description
npm run dev	Start the Vite dev server
npm run build	Build for production (runs icon generation first)
npm run preview	Preview the production build locally
npm test	Run all tests
npm run test:unit	Run unit tests only
npm run test:integration	Run integration tests
npm run test:watch	Run tests in watch mode
npm run test:coverage	Run tests with coverage report
npm run lint	Lint source
npm run format	Format source

---

8. Commit & Push Your Changes

git add .
git commit -m "fix: describe your change"

# Push to your fork's dev branch
git push origin fix/my-changes

# Or if working directly on dev
git push origin dev

Then open a Pull Request from your fork to mauriceboe/TREK targeting the dev branch. If your PR only modifies files under wiki/, it is exempt from branch enforcement and may target any branch.

---

Tips

• Always branch off from an up-to-date dev — run git fetch upstream && git rebase upstream/dev before starting new work.
• Run tests before pushing: npm test at the repo root runs all workspaces.
• Follow the commit message conventions described in the Contributing guidelines.