zuplo 6.72.14 → 6.72.16

package/docs/articles/local-development-debugging.mdx

@@ -3,18 +3,41 @@ title: "Debugging Locally"
 sidebar_label: Debugging
 ---
 
-You can debug your local gateway through VS Code using its TypeScript debugger.
-Features such as breakpoints, stepping through the code, variable inspection,
-etc., will be available to help you debug your gateway.
+Set breakpoints, step through code, and inspect variables in your route handlers
+and custom policies while your gateway runs locally.
 
-1. Create a `.vscode/launch.json` file with the following content. If you
-   already have an older/existing `.vscode/launch.json` file, you can add the
-   section in the curly braces to the configurations array. Take note of the
-   port value since that's the value you will specify next.
+## VS Code
 
-```json
+New projects created with `create-zuplo-api` ship with a `.vscode/launch.json`
+that's ready to go.
+
+<Stepper>
+
+1. Open **Run and Debug** (View > Run and Debug).
+
+1. Select **Launch & Attach Zuplo** and click the green play button.
+
+1. Set a breakpoint, then send a request to the route. See
+   [Breakpoints not binding?](#breakpoints-not-binding) if it doesn't stop.
+
+</Stepper>
+
+If your project doesn't have a `.vscode/launch.json`, create one with these
+contents and repeat the steps above:
+
+```json title=".vscode/launch.json"
 {
+  "version": "0.2.0",
   "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Launch Zuplo",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["zuplo", "dev", "--debug-port", "9229", "--port", "9000"],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
+    },
     {
       "name": "Zuplo Gateway",
       "type": "node",
@@ -22,23 +45,54 @@ etc., will be available to help you debug your gateway.
       "restart": true,
       "port": 9229
     }
+  ],
+  "compounds": [
+    {
+      "name": "Launch & Attach Zuplo",
+      "configurations": ["Launch Zuplo", "Zuplo Gateway"]
+    }
   ]
 }
 ```
 
-2. Start the gateway in debug mode using the port that you specified above.
+## WebStorm, IntelliJ, and other editors
 
-```bash
-npx zuplo dev --debug-port 9229
-```
+<Stepper>
+
+1. Start the gateway with the debug port open:
+
+   ```bash
+   npx zuplo dev --debug-port 9229
+   ```
+
+1. Add an **Attach to Node.js/Chrome** run configuration pointed at
+   `localhost:9229` and run it in debug mode. In JetBrains IDEs, enable
+   **Reconnect automatically** so it re-attaches after each reload.
+
+1. Set a breakpoint, then send a request to the route. See
+   [Breakpoints not binding?](#breakpoints-not-binding) if it doesn't stop.
+
+</Stepper>
+
+:::caution
+
+Don't use "Debug the `npm run dev` script." Your policies run in a separate
+runtime process, so debugging the npm script attaches to the wrong process and
+breakpoints never bind. Always start with `--debug-port` and attach to it, as
+above.
+
+:::
+
+## Breakpoints not binding?
 
-3. Switch to the View > Run and Debug in VS Code. You can now attach the
-   debugger by selecting **Zuplo Gateway** and clicking the green triangle.
+A breakpoint may show as **unbound** (a hollow marker) until the route runs for
+the first time — each policy is loaded on first use, so the debugger has nothing
+to attach to until then. To fix it:
 
-![VS code debugging](../../public/media/local-development-debugging/image.png)
+1. Send a request to the route once. The breakpoint marker turns solid.
+1. Send the request again — execution now stops at your breakpoint.
 
 ## Limitations
 
-- We only support stepping through your own module code. System code provided by
-  Zuplo are minified and stripped of source maps, so you won't be able to step
-  through them.
+You can only step through your own code. System code provided by Zuplo is
+minified and stripped of source maps, so you can't step into it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.72.14",
+  "version": "6.72.16",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.72.14",
-    "@zuplo/core": "6.72.14",
-    "@zuplo/runtime": "6.72.14",
+    "@zuplo/cli": "6.72.16",
+    "@zuplo/core": "6.72.16",
+    "@zuplo/runtime": "6.72.16",
     "@zuplo/test": "1.4.0"
   }
 }