Next.js Debugging App

This repository contains a Next.js application configured for easy debugging in Visual Studio Code. It includes client-side React pages, server-side API routes, a VS Code debug configuration, and notes about environment variables and tooling.

Contents

• .vscode/launch.json — VS Code debug configurations (server + client + attach).
• app/ — Next.js app route files and React components (client).
• app/api/... — API routes (server).
• docs/DEBUGGING.md — short troubleshooting & usage guide.
• dockerfile — optional development container (Debian-based).
• .env.local — example env file for local development.

---

Prerequisites

• Node.js (recommended LTS, e.g., 18/20)
• npm (or yarn/pnpm)
• Visual Studio Code (with the "Debugger for Chrome"/built-in JS debugger)
• Install project deps:

cd e:/OnSpecDev/nextjs-debugging-app
npm install

---

Run the app (development)

• Normal dev:

npm run dev
# or
next dev

• Start server with Node inspector (for VS Code to attach):

npm run dev:debug
# (This runs Next.js with --inspect=9229 so VS Code can attach)

Make sure package.json contains:

{
  "scripts": {
    "dev": "next dev",
    "dev:debug": "node --inspect=9229 ./node_modules/next/dist/bin/next dev"
  }
}

---

VS Code Debugging (what's provided)

A .vscode/launch.json is included with:

• "Next: Launch (dev)" — launches npm run dev:debug and attaches the VS Code node debugger to the Next.js server.
• "Next: Attach to server" — attach to an already-running process on port 9229.
• "Next: Client (Chrome)" and "Next: Client (Edge)" — launch a browser with remote debugging and map client source files via source maps.
• Compound "Next: Full (server + client)" — starts both server and client debug sessions together.

How to use:

1. Open Run and Debug (Ctrl+Shift+D).
2. Select "Next: Full (server + client)" and press Start (green arrow).
3. Set breakpoints in server files (app/api/..., route.ts) or client .tsx files (e.g., app/fetch-test.tsx).
4. Interact with the app in the launched browser. Breakpoints should pause execution.

---

Source maps & TypeScript

Ensure source maps are enabled so breakpoints map to original TypeScript:

• tsconfig.json should include:

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true
  }
}

If breakpoints do not bind: confirm compiled files include source maps and that the debugger's webRoot matches the workspace root.

---

.env.local (explanation and usage)

A sample .env.local is provided in the repo:

NEXT_PUBLIC_SENTRY_DSN=your_public_dsn
SENTRY_DSN=your_server_dsn
SENTRY_AUTH_TOKEN=your_sentry_auth_token
SENTRY_ORG=your_org
SENTRY_PROJECT=your_project

Notes:

• Variables starting with NEXT_PUBLIC_ are exposed to the browser. Do not put secrets there.
• SENTRY_DSN (no NEXT_PUBLIC_) is intended for server-side usage only.
• Replace placeholder values with real values for production/staging.
• Never commit secrets to version control. Add .env.local to .gitignore and store production secrets in your deployment provider (Vercel/Netlify/Azure/etc.) or a secrets manager.

---

Docker / Development container notes

• A development Dockerfile exists for Debian-based containers. It installs curl, bash, git, and attempts to install cline.
• The cline npm package may not support Windows host installs. If using the container, building and running it (Linux) avoids host platform restrictions.
• Alternative on Windows: use WSL2 or install nvm-windows / nvm to manage Node versions.

---

Troubleshooting

• ESLint / config not picked up: ensure ESLint config file is at the workspace root and dependencies are installed.
• Breakpoints not hit:
  • Server breakpoints: confirm you started Next.js with --inspect=9229 (use npm run dev:debug) and either launch or attach with VS Code to port 9229.
  • Client breakpoints: use the Chrome/Edge debug configuration; ensure webRoot is correct and source maps are present.
• To inspect resolved ESLint config for a file:

npx eslint --print-config app/fetch-test.tsx

• To debug ESLint resolution:

npx eslint "app/fetch-test.tsx" --ext .tsx --debug

---

Debugging guide / quick checklist

1. npm install
2. Open VS Code in the repo root
3. Ensure tsconfig.json has sourceMap enabled
4. Start "Next: Full (server + client)" in Run and Debug
5. Set breakpoints in server or client files
6. If server breakpoints not hit: start npm run dev:debug then "Attach to server"
7. For browser debugging, use the Chrome/Edge launch config that opens http://localhost:3000

---

Security & production

• Keep secrets out of the repo. Use environment variables in production hosting.
• Validate that any client-exposed environment variables (NEXT_PUBLIC_*) do not reveal secrets.

---

Where to find help

• VS Code debugging docs: https://code.visualstudio.com/docs/editor/debugging
• Next.js debugging / source maps: Next.js docs and GitHub issues for mapping client/server stacks
• If something in this repo fails, open an issue including:
  • Node version
  • npm install output
  • output of npm run dev:debug or the VS Code Debug console

---