# How to Set Up the TREK Development Environment: A Complete Guide > Set up the TREK development environment quickly. Follow this guide to clone the repo, install dependencies, and run the full stack locally. - Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK) - Tags: how-to-guide - Published: 2026-07-10 --- **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`](https://github.com/mauriceboe/TREK/blob/main/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: ```bash 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: ```bash git remote add upstream git@github.com:mauriceboe/TREK.git ``` Before starting any feature work, fetch and rebase the latest changes: ```bash 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`: ```bash 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`](https://github.com/mauriceboe/TREK/blob/main/package.json) defines this workspace structure. Install all dependencies with a single command: ```bash 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: ```bash 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`](https://github.com/mauriceboe/TREK/blob/main/server/src/config.ts) to initialize the extractor. ## Start the Development Server Run the complete application stack from the repository root: ```bash npm run dev ``` This command executes the `dev` script defined in the root [`package.json`](https://github.com/mauriceboe/TREK/blob/main/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: ```bash # 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: ```bash npm test ``` For workspace-specific testing, navigate to the directory and run targeted commands: ```bash cd server && npm run test:e2e # End-to-end tests only ``` Ensure code consistency before committing: ```bash 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: ```bash 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: ```bash 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: ```bash 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`](https://github.com/mauriceboe/TREK/blob/main/server/src/config.ts).