How to Set Up the TREK Development Environment: A Complete Guide

To set up the TREK development environment, fork the repository, clone the dev branch, run npm ci to install monorepo dependencies, and execute npm run dev to start the full stack locally.

TREK is a modern travel management application built as an npm workspace monorepo containing a React frontend, NestJS backend, and shared TypeScript libraries. Setting up the TREK development environment requires Node.js 22+, Git, and familiarity with monorepo workflows. This guide walks through the exact steps documented in the official repository at mauriceboe/TREK.

Prerequisites

Before cloning the repository, ensure your workstation meets these requirements:

• Node.js 22+ (Latest LTS) – The project targets modern Node.js features as specified in package.json.
• npm – Bundled with Node.js for workspace package management.
• Git – Required for version control and branch management.
• GitHub account – Necessary for forking the repository.

Fork and Clone the Repository

TREK uses the dev branch as its active development branch. Fork the repository on GitHub, then clone your fork specifically checking out this branch:

git clone -b dev git@github.com:YOUR_USERNAME/TREK.git
cd TREK

This ensures you are working with the latest unstable features and bug fixes rather than the production main branch.

Configure Git Remotes and Sync

Add the upstream remote to keep your fork synchronized with the main project:

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

Before starting any feature work, fetch and rebase the latest changes:

git fetch upstream
git rebase upstream/dev

This workflow prevents merge conflicts and ensures your contributions apply cleanly to the current codebase.

Create a Feature Branch

Isolate your changes by creating a dedicated branch off origin/dev:

git checkout -b feat/your-feature-name origin/dev

Follow the project's branch naming conventions:

• feat/short-description – New features
• fix/short-description – Bug fixes
• chore/short-description – Maintenance tasks

Install Monorepo Dependencies

TREK organizes code into three workspaces: client, server, and shared. The root package.json defines this workspace structure. Install all dependencies with a single command:

npm ci

This installs dependencies for all workspaces simultaneously, linking the shared package for local development.

Optional: Enable Booking Import with KItinerary

To activate the booking-import feature for parsing travel itineraries, install the KDE KItinerary binary and configure environment variables:

sudo apt-get install -y libkitinerary-bin

export KITINERARY_EXTRACTOR_PATH=/usr/local/bin/kitinerary-extractor
export QT_QPA_PLATFORM=offscreen
export XDG_CACHE_HOME=/tmp/kf6-cache

Add these exports to a .env file in the repository root. The server reads these variables at startup via server/src/config.ts to initialize the extractor.

Start the Development Server

Run the complete application stack from the repository root:

npm run dev

This command executes the dev script defined in the root package.json, which:

1. Builds the shared package
2. Starts the shared watcher
3. Launches the NestJS backend (server)
4. Starts the Vite client dev server with hot-module replacement

Open http://localhost:3000 to access the application. The UI automatically connects to the local WebSocket server.

Individual Workspace Development

Alternatively, run workspaces separately for focused debugging:

# Terminal 1 - Backend

cd server && npm run dev

# Terminal 2 - Frontend  

cd client && npm run dev

Running Tests and Code Quality

Execute the comprehensive test suite across all workspaces:

npm test

For workspace-specific testing, navigate to the directory and run targeted commands:

cd server && npm run test:e2e  # End-to-end tests only

Ensure code consistency before committing:

npm run lint          # Check all workspaces

npm run format        # Auto-fix formatting

npm run format:check  # Verify without modifying files

Build for Production

When ready to create a production bundle:

npm run build

This builds the shared package first, then the server, then the client. Output assets appear in client/dist, while the server compiles to its dist directory. Start the production server with:

npm start

Configuration and Environment Variables

Several environment variables control runtime behavior. Create a .env file in the repository root with these common options:

Encryption Key: Generate a secure key for local development:

openssl rand -hex 32

Set this as ENCRYPTION_KEY in your .env. The server auto-generates a temporary key if none is provided, but explicit configuration is recommended for persistent data.

OIDC/SSO: When enabling OpenID Connect, ensure APP_URL points to the reachable host. This URL is required for generating correct email links and callback URLs.

Docker Warning: If testing with Docker locally, only mount ./data and ./uploads volumes. Do not mount the entire /app directory, as this overwrites the built application files inside the container.

Summary

• Fork and clone the dev branch to access the latest development code.
• Run npm ci at the root to install all workspace dependencies in one step.
• Execute npm run dev to start the full stack, or run workspaces individually for targeted development.
• Configure KItinerary environment variables to enable booking import functionality.
• Use npm test and npm run lint to verify code quality before submitting pull requests.
• Set ENCRYPTION_KEY and APP_URL environment variables for proper local operation.

Frequently Asked Questions

What Node.js version is required for TREK development?

TREK requires Node.js 22+ (the latest LTS release). The project utilizes modern Node.js features and npm workspace capabilities introduced in recent versions. Check your version with node --version before running npm ci.

How do I keep my fork synchronized with the main repository?

Add the upstream remote with git remote add upstream git@github.com:mauriceboe/TREK.git, then run git fetch upstream followed by git rebase upstream/dev before creating new feature branches. This ensures you are coding against the most recent commits.

Can I run just the backend or frontend separately?

Yes. Navigate to the specific workspace directory and run npm run dev. Use cd server && npm run dev to start only the NestJS backend in watch mode, or cd client && npm run dev to launch only the Vite frontend server. This is useful when debugging specific components without the overhead of the full stack.

Why is the booking import feature not working locally?

The booking import feature requires the KItinerary binary (kitinerary-extractor) and specific environment variables including KITINERARY_EXTRACTOR_PATH and QT_QPA_PLATFORM. Without these configured in your .env file, the server skips initialization of the booking parser as implemented in server/src/config.ts.

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