NeilClack
cc4aa8717e
Disable Vite's ANSI output (NO_COLOR/FORCE_COLOR) so the background-task problem matcher's endsPattern reliably matches, fixing the 'Error exists after running preLaunchTask' failure. Add a 'Launch Debuggable Chrome' task (:9222, persistent ~/.chrome-rw-debug profile) and an attach compound so you can debug the frontend in a Chrome you control and stay logged in. Update DEBUGGING.md.
96 lines
4.0 KiB
Markdown
96 lines
4.0 KiB
Markdown
# 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.
|