# Debugging the Portal in VS Code

Two independent debug targets: **backend** (server-side SvelteKit code) and
**frontend** (client-side Svelte/browser code). Pick from the Run and Debug
panel (⇧⌘D).

## Backend (server-side code)

Breakpoints work in `+page.server.ts`, `+server.ts`, `$lib/server/**`,
`hooks.server.ts`, `src/lib/db.ts`, etc.

1. Run and Debug → **"Backend: Attach to Dev Server"** (or press F5 with it
   selected). It starts the dev server (Vite with the Node inspector on
   `:9229`) and attaches automatically.
2. Open a server file, click in the gutter to set a breakpoint, then interact
   with the app — the breakpoint hits.

Alternatives:

- **"Backend: Launch Dev Server"** — VS Code starts Vite itself and debugs it
  directly (no separate task). Good if you want to stop/restart cleanly.
- **"Backend: Attach (no server start)"** — attach when the server is already
  running with the inspector (used by the Full Stack compound).

> **Why not `npm run dev`?** `NODE_OPTIONS=--inspect` on `npm` puts the
> inspector on the _npm_ process, not Vite, so your breakpoints never hit. The
> tasks/configs run `./node_modules/.bin/vite` **directly** so the inspector owns
> the process that actually executes the SSR code.

## Frontend (client-side code)

Breakpoints work in `.svelte` `<script>` blocks and `$lib/**`.

1. Run and Debug → **"Frontend: Chrome"**. This launches Google Chrome, starts
   the dev server if needed, and maps Vite's served modules back to your source
   files. Breakpoints in the Sources panel and in VS Code both work.
2. If Chrome is already open with your logged-in session, start it once with a
   debug port and use **"Frontend: Chrome (attach)"**:
   ```sh
   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
     --remote-debugging-port=9222 --user-data-dir=/tmp/rw-chrome
   ```

### Use your own (logged-in) Chrome — recommended workflow

If you'd rather keep using a Chrome you control (logged in, extensions, etc.):

1. Run the task **Terminal → Run Task… → "Launch Debuggable Chrome"**. This
   opens Chrome with the debugging port on `:9222` using a dedicated profile at
   `~/.chrome-rw-debug`, so it can run alongside your normal Chrome.
2. Log in once (the profile is persistent, so you only do this the first time)
   and navigate to `http://localhost:5173`.
3. Make sure the dev server is running (task **"Start Dev Server"**), then start
   the launch profile **"Frontend: Chrome (attach)"** (or press F5 with it
   selected). Breakpoints in VS Code and Chrome DevTools both work.

Handy shortcut: **"Frontend: Attach to my Chrome (starts server)"** starts the
dev server and attaches in one step (Chrome still needs to be debuggable from
step 1).

If Chrome is already open but _without_ the debugging port, VS Code cannot
attach — close it and relaunch via the task. Launching your everyday Chrome
with `--remote-debugging-port` also works; the task just avoids disturbing that
profile.

### Safari

VS Code has **no Safari debugger**, so client-side breakpoints in the VS Code
editor require a Chromium browser (Chrome/Edge/Brave). You can still debug
Safari, just in Safari's own tools:

1. Safari → Settings → Advanced → enable **"Show features for web developers"**.
2. Develop menu → **Show Web Inspector** (⌥⌘I) → Sources tab.
3. Set breakpoints there. Source maps are served by Vite, so you'll see your
   `.svelte` and `.ts` files, not compiled output.

For the best editor-integrated experience, install Chrome:

```sh
brew install --cask google-chrome
```

## Full stack

**"Full Stack (Backend + Chrome)"** in the compounds list starts exactly one
dev server, attaches the Node debugger, and opens Chrome — debug both sides at
once.

## Notes

- Only one process can bind `:9229` (inspector) and one `:5173` (dev server).
  If a launch fails with "address already in use", stop the other server or run
  `pkill -f "vite dev"`.
- The dev server task keeps its terminal open ("Terminal" panel) so you can see
  Vite output and the inspector URL.