Spaces:
Sleeping
Sleeping
File size: 10,566 Bytes
cb43fbd | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 | # 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](https://github.com/mauriceboe/TREK) and click **Fork** to create your own copy.
Then clone your fork locally:
```bash
# 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:
```bash
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:
```bash
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:
```bash
# 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:
```bash
npm ci
```
---
## 6. Optional: KItinerary (Booking Import)
The booking-confirmation import feature uses [KDE KItinerary](https://apps.kde.org/itinerary/) 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:
```bash
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
```bash
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):
```bash
# 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
```bash
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. |