# How to Debug TREK Code: Essential Strategies for the Travel Planner Stack

> Learn to debug TREK code effectively. Explore strategies for full-stack debugging, Node debugger attachment, WebSocket inspection, and environment variable verification to pinpoint and resolve issues.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: how-to-guide
- Published: 2026-07-10

---

**Debug TREK code by running the full-stack app in development mode with source maps enabled, attaching a Node debugger to the NestJS backend on port 9229, inspecting WebSocket traffic in browser DevTools, and verifying environment variables like `ENCRYPTION_KEY` and `LOG_LEVEL` to isolate runtime failures.**

TREK is a full-stack, real-time collaborative travel planner built with a **NestJS** backend and **React 19** frontend. When learning how to debug TREK code, you must account for its three-layer architecture: the SQLite-backed API server, the Vite-powered client, and the WebSocket synchronization layer that keeps trip data in sync across users.

## Understanding the TREK Architecture

Before diving into specific debugging tactics, map the codebase to its runtime layers:

| Layer | Technologies | Key Entry Points |
|-------|--------------|------------------|
| **Backend** | NestJS 11, TypeScript, SQLite | [[`server/src/main.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts)](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts) bootstraps the app; [[`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts)](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts) handles real-time channels. |
| **API Security** | SSRF Guard, Crypto utils | [[`server/src/utils/ssrfGuard.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/utils/ssrfGuard.ts)](https://github.com/mauriceboe/TREK/blob/main/server/src/utils/ssrfGuard.ts) validates outbound HTTP; [[`server/src/utils/crypto.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/utils/crypto.ts)](https://github.com/mauriceboe/TREK/blob/main/server/src/utils/crypto.ts) manages `ENCRYPTION_KEY` logic. |
| **Frontend** | React 19, Zustand, Vite, Tailwind | [[`client/src/App.tsx`](https://github.com/mauriceboe/TREK/blob/main/client/src/App.tsx)](https://github.com/mauriceboe/TREK/blob/main/client/src/App.tsx) is the root component; feature folders like `client/src/components/Weather/` contain UI logic. |
| **Real-time Sync** | WebSocket (`ws`) | Clients connect to `/ws` (requires reverse-proxy configuration for upgrade). |
| **Add-ons** | Dynamic modules | Schemas in `shared/src/*` (e.g., [[`shared/src/trip/trip.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/trip/trip.schema.ts)](https://github.com/mauriceboe/TREK/blob/main/shared/src/trip/trip.schema.ts)) validate toggled features. |

## Backend Debugging Techniques

### Inspect Server Logs

TREK writes runtime logs to `data/logs/trek.log`. Adjust verbosity by setting the `LOG_LEVEL` environment variable from `info` to `debug` in your `.env` file.

For encryption-related failures, trace the key derivation logic in [[`server/src/utils/crypto.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/utils/crypto.ts)](https://github.com/mauriceboe/TREK/blob/main/server/src/utils/crypto.ts). A missing or malformed `ENCRYPTION_KEY` causes immediate startup crashes.

### Attach VS Code Debugger

Configure your [`launch.json`](https://github.com/mauriceboe/TREK/blob/main/launch.json) to attach to the Node process on port 9229. Set breakpoints directly in [[`server/src/main.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts)](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts) or within any NestJS service to inspect request pipelines.

```json
{
  "type": "node",
  "request": "attach",
  "name": "Attach to TREK",
  "port": 9229
}

```

### Debug WebSocket Handlers

Insert logging inside [[`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts)](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts) to trace message flow:

```typescript
// server/src/websocket.ts
ws.on('message', (msg) => {
  console.debug('WS message received:', msg);
  // Process synchronization logic...
});

```

## Frontend Debugging Strategies

### React Component Inspection

For UI bugs, start with high-traffic components like [[`client/src/components/Weather/WeatherWidget.tsx`](https://github.com/mauriceboe/TREK/blob/main/client/src/components/Weather/WeatherWidget.tsx)](https://github.com/mauriceboe/TREK/blob/main/client/src/components/Weather/WeatherWidget.tsx) or [`TripFormModal.tsx`](https://github.com/mauriceboe/TREK/blob/main/TripFormModal.tsx). Use Chrome or Firefox DevTools to inspect the component tree and verify Tailwind class applications directly in the JSX.

### Zustand State Debugging

Since TREK uses **Zustand** for client state, you can dump the entire store to the console at any time:

```typescript
// Anywhere in the client codebase
import { useStore } from '@/store';
console.log('Current store state:', useStore.getState());

```

This reveals whether state updates triggered by WebSocket messages actually reached the UI layer.

## WebSocket Connection Troubleshooting

Connection drops between the React client and NestJS server usually stem from reverse-proxy misconfigurations.

1. Open browser DevTools → **Network** → filter by **WS**.
2. Verify the client successfully upgrades to `/ws`.
3. If the connection fails, ensure your Nginx (or equivalent) includes a `location /ws` block to forward WebSocket traffic.

Check the README for recommended reverse-proxy examples that handle the WebSocket upgrade headers.

## Environment Configuration and Common Pitfalls

Missing environment variables are the most common cause of TREK startup failures. Use `.env.example` as your template and never commit real secrets.

| Symptom | Likely Cause | Quick Fix |
|---------|--------------|-----------|
| Server crashes on start | Missing `ENCRYPTION_KEY` or invalid `ADMIN_*` credentials | Generate a key via `openssl rand -hex 32`, set `ADMIN_EMAIL` and `ADMIN_PASSWORD`. |
| WebSocket connection refused | Reverse-proxy not forwarding `/ws` | Add the `location /ws` block from the README examples. |
| API returns 500 for external HTTP calls | SSRF guard blocking the URL | Add the domain to `ALLOW_INTERNAL_NETWORK` (security-sensitive). |
| UI not updating after state change | WebSocket message lost or state not syncing | Verify the client receives the `update` event in [[`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts)](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts). |

## Testing and Plugin Development

Run the Vitest suite to catch regressions early:

```bash
npm test

```

Run a single spec in watch mode for targeted feedback:

```bash
npx vitest run shared/src/weather/weather.schema.spec.ts --watch

```

For plugin developers, use the **plugin-sdk** CLI to validate manifests:

```bash
npm run sdk:dev        # Launches sandbox with hot-reload

npx ts-node plugin-sdk/src/cli/validate.ts ./my-plugin/manifest.json

```

## Performance Profiling

TREK ships with two helper scripts for performance analysis. After recording a Chrome DevTools performance trace, run:

```bash
node scripts/analyze-react-profiler.cjs trace.json
node scripts/analyze-devtool-profiler.cjs trace.json

```

These pinpoint React render bottlenecks or slow JavaScript execution in the event loop.

## Summary

- **Start with logs**: Check `data/logs/trek.log` and adjust `LOG_LEVEL` to `debug` for verbose output.
- **Use source maps**: Run `npm run dev` to enable hot-reload and full source-map support for both frontend and backend.
- **Attach a debugger**: Connect VS Code to the Node process on port 9229 to breakpoint NestJS services.
- **Trace WebSocket issues**: Verify `/ws` upgrade in browser DevTools and log messages in [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts).
- **Validate state**: Log `useStore.getState()` to debug Zustand state mismatches.
- **Check environment**: Ensure `ENCRYPTION_KEY`, `ADMIN_EMAIL`, and `ADMIN_PASSWORD` are set before startup.

## Frequently Asked Questions

### Why does my TREK server crash immediately on startup?

The NestJS backend requires a valid `ENCRYPTION_KEY` and admin credentials to bootstrap. Generate a secure key with `openssl rand -hex 32`, set it in your `.env` file alongside `ADMIN_EMAIL` and `ADMIN_PASSWORD`, then restart. Without these variables, the crypto utilities in [`server/src/utils/crypto.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/utils/crypto.ts) throw fatal errors.

### How do I debug why my React UI is not updating when trip data changes?

First, verify the WebSocket connection is active in browser DevTools under the Network → WS tab. Then, log the Zustand store state using `console.log(useStore.getState())` to confirm the client received the update. If the store updated but the UI did not, check the React component's subscription to the specific store slice in [`client/src/App.tsx`](https://github.com/mauriceboe/TREK/blob/main/client/src/App.tsx) or related feature folders.

### Where can I find logs for failed outgoing HTTP requests made by the server?

TREK logs outbound HTTP activity and SSRF rejections to `data/logs/trek.log`. If a request returns 500, check if the URL was blocked by [`server/src/utils/ssrfGuard.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/utils/ssrfGuard.ts). You can temporarily allow internal network ranges by setting `ALLOW_INTERNAL_NETWORK`, though this reduces security protections.

### How do I run a single unit test when debugging a schema validation error?

Use Vitest's file filter with the `--watch` flag to isolate the failing test. For example, run `npx vitest run shared/src/weather/weather.schema.spec.ts --watch` to continuously execute only the weather schema specs. This provides rapid feedback while you modify validation logic in the shared layer.