Add brief troubleshooting section on using IDE debugger

[tjcrowder]

I understand that the goal of the docs is to "only document how Astro works" and that makes good sense, but I think it would be helpful to newcomers if the Troubleshooting section at least mentioned it's possible to debug Astro code with most IDEs. 🙂 It's not hard to figure out, but the first thing I did was look in the docs for instructions.

Happy to do a PR for this. I wrote up a slightly-detailed version but then realized it probably wouldn't be in keeping with the spirit above, but perhaps something like:

Debugging in your IDE

You can debug both your server- and client-side project code directly in most IDEs.

• Server: The Astro dev server is a standard Node process. Configure your IDE to run node ./node_modules/.bin/astro dev from your project root and attach to the new process. That will let you debug server-side code (SSR, API endpoints).
• Client: Configure your IDE to run the browser pointing to http://localhost:4321/.

If you use VS Code and bootstrapped your project with npm create astro@latest, it will already have a .vscode/launch.json file providing a configuration for server-side debugging.

FWIW, here's the long version that probably isn't appropriate (too specific to VS Code), but I already wrote it, so:

Debugging in your IDE

You can debug server- and client-side code directly in most IDEs. Here's how:

If you bootstrapped your project with npm create astro@latest, it will have a .vscode/launch.json configuration for server-side debugging that will work for VS Code:

{
  "version": "0.2.0",
  "configurations": [
    {
      "command": "./node_modules/.bin/astro dev",
      "name": "Development server",
      "request": "launch",
      "type": "node-terminal"
    }
  ]
}

For other IDEs, simply configure a debug launch command to run node ./node_modules/.bin/astro dev from your project root and attach to the new process.

If you have client-side code, you can debug it in the devtools of your browser, or configure your IDE to debug it. Here's an example configuration for launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "command": "./node_modules/.bin/astro dev",
      "name": "Development server",
      "request": "launch",
      "type": "node-terminal"
      },
      {
        "type": "chrome",
        "request": "launch",
        "name": "Launch browser - localhost:4321",
        "url": "http://localhost:4321",
        "webRoot": "${workspaceFolder}/src",
        "sourceMapPathOverrides": {
          "vite:///src/*": "${webRoot}/*"
        },
        "skipFiles": ["**/node_modules/**"]
      }
  ]
}

(Optionally add the runtimeExecutable option to run another devtools-compatible browser.)

If your IDE supports "compounds," you can use one to launch both the Astro dev process and the browser:

{
  "version": "0.2.0",
  "configurations": [
    {
      "command": "./node_modules/.bin/astro dev",
      "name": "Development server",
      "request": "launch",
      "type": "node-terminal"
      },
      {
        "type": "chrome",
        "request": "launch",
        "name": "Launch browser - localhost:4321",
        "url": "http://localhost:4321",
        "webRoot": "${workspaceFolder}/src",
        "sourceMapPathOverrides": {
          "vite:///src/*": "${webRoot}/*"
        },
        "skipFiles": ["**/node_modules/**"]
      }
  ],
  "compounds": [
    {
      "name": "Full Stack",
      "configurations": ["Development server", "Launch browser - localhost:4321"]
    }
  ]
}

Just let me know if I should do a PR for either of those (and if so, any edits you want done beforehand). And thank you for the awesome docs!