Files

T

NeilClack 04e1f79f37 chore(vscode): separate backend and frontend debug configs

Backend configs run Vite directly (not via npm run dev) so the Node
inspector owns the process that executes SSR code, with source maps
enabled for .ts server files. Frontend configs launch/attach Chrome.
Adds a Node-inspector dev task, a Full Stack compound, and DEBUGGING.md
documenting the Safari limitation and workflows.

2026-09-29 13:29:55 -05:00

2.9 KiB

Raw Blame History

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.

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.
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/**.

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.

If Chrome is already open with your logged-in session, start it once with a debug port and use "Frontend: Chrome (attach)":

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 --user-data-dir=/tmp/rw-chrome

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:

Safari → Settings → Advanced → enable "Show features for web developers".
Develop menu → Show Web Inspector (⌥⌘I) → Sources tab.
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:

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.

2.9 KiB Raw Blame History