docs: Debugging Edge Functions with Inspector (#27014)

* chore: update ai types.

* docs: start ef inspector docs.

* chore: break out into own page.

* chore: spelling.

* chore: chrome devtools only.

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts

@@ -1145,6 +1145,10 @@ export const functions: NavMenuConstant = {
           name: 'Debugging Edge Functions',
           url: '/guides/functions/debugging',
         },
+        {
+          name: 'Debugging Tools',
+          url: '/guides/functions/debugging-tools',
+        },
         {
           name: 'Logging and Using Headers',
           url: '/guides/functions/functions-headers',

apps/docs/content/guides/functions/ai-models.mdx

@@ -19,7 +19,11 @@ const model = new Supabase.ai.Session('model-name')
 
 <Admonition type="tip">
 
-To get type hints and checks for the API we recommend adding this triple-slash directive to the start of the Edge Function code: `/// <reference types="https://esm.sh/@supabase/functions-js/src/edge-runtime.d.ts" />`
+To get type hints and checks for the API you can import types from `functions-js` at the top of your file:
+
+```ts
+import 'https://esm.sh/@supabase/functions-js/src/edge-runtime.d.ts'
+```
 
 </Admonition>
 
@@ -95,7 +99,7 @@ Inference via larger models is supported via [Ollama](https://ollama.com/). In t
    ```
 
    ```ts
-   /// <reference types="https://esm.sh/@supabase/functions-js/src/edge-runtime.d.ts" />
+   import 'https://esm.sh/@supabase/functions-js/src/edge-runtime.d.ts'
    const session = new Supabase.ai.Session('mistral')
 
    Deno.serve(async (req: Request) => {

apps/docs/content/guides/functions/debugging-tools.mdx

@@ -0,0 +1,23 @@
+---
+id: 'functions-debugging-tools'
+title: 'Debugging Tools'
+description: 'Debugging Tools for Edge Functions.'
+subtitle: 'Debugging Tools for Edge Functions.'
+---
+
+Since [v1.171.0](https://github.com/supabase/cli/releases/tag/v1.171.0) the Supabase CLI supports debugging Edge Functions via the v8 inspector protocol, allowing for debugging via [Chrome DevTools](https://developer.chrome.com/docs/devtools/) and other Chromium-based browsers.
+
+### Inspect with Chrome Developer Tools
+
+You can use the [Chrome DevTools](https://developer.chrome.com/docs/devtools/) to set breakpoints and inspect the execution of your Edge Functions.
+
+1. Serve your functions in [inspect mode](/docs/reference/cli/supabase-functions-serve): `supabase functions serve --inspect-mode brk`. This will set a breakpoint at the first line to pause script execution before any code runs.
+1. In your Chrome browser navigate to `chrome://inspect`.
+1. Click the "Configure..."" button to the right of the Discover network targets checkbox.
+1. In the Target discovery settings dialog box that opens, enter `127.0.0.1:8083` in the blank space and click the "Done" button to exit the dialog box.
+1. Click "Open dedicated DevTools for Node" to complete the preparation for debugging. The opened DevTools window will now listen to any incoming requests to edge-runtime.
+1. Send a request to your function running locally, e.g. via curl or Postman. The DevTools window will now pause script execution at first line.
+1. In the "Sources" tab navigate to `file://` > `home/deno/functions/<your-function-name>/index.ts`.
+1. Use the DevTools to set breakpoints and inspect the execution of your Edge Function.
+
+![Debugging in Chrome DevTools.](/docs/img/guides/functions/debug-chrome-devtools.png)

apps/docs/content/guides/functions/debugging.mdx

@@ -69,7 +69,7 @@ If you encounter any problems or issues with your Edge Functions, here are some
 
 ### Unable to deploy Edge Function
 
-- Make sure you're on the latest version of the [Supabase CLI](/docs/guides/cli#updates).
+- Make sure you're on the latest version of the [Supabase CLI](/docs/guides/cli#updates).
 - If the output from the commands above does not help you to resolve the issue, open a support ticket via the Supabase Dashboard (by clicking the "Help" button at the top right) and include all output from the commands mentioned above.
 
 ### Unable to call Edge Function
@@ -88,7 +88,7 @@ If your Edge Function takes too long to respond or times out:
 - Navigate to the [Functions section](https://supabase.com/dashboard/project/_/functions) in your dashboard, select your function from the list, and click `Logs`.
 - In the logs, look for the `booted` event and check if they have consistent boot times.
   - If the boot times are similar, it’s likely an issue with your function’s code, such as a large dependency, a slow API call, or a complex computation. You can try to optimize your code, reduce the size of your dependencies, or use caching techniques to improve the performance of your function.
-  - If only some of the `booted` events are slow, find the affected `region` in the metadata and submit a support request via the "Help" button at the top.
+  - If only some of the `booted` events are slow, find the affected `region` in the metadata and submit a support request via the "Help" button at the top.
 
 ### Receiving 546 Error Response
 
@@ -99,10 +99,10 @@ The 546 error response might occur because:
 
 ### Issues serving Edge Functions locally with the Supabase CLI
 
-- Make sure you're on the latest version of the [Supabase CLI](/docs/guides/cli#updates).
-- Run the serve command with the `-debug` flag.
+- Make sure you're on the latest version of the [Supabase CLI](/docs/guides/cli#updates).
+- Run the serve command with the `-debug` flag.
 - Support engineers can then try to run the provided sample code locally and see if they can reproduce the issue.
-- Search the [Edge Runtime](https://github.com/supabase/edge-runtime) and [CLI](https://github.com/supabase/cli) repos for the error message, to see if it has been reported before.
+- Search the [Edge Runtime](https://github.com/supabase/edge-runtime) and [CLI](https://github.com/supabase/cli) repos for the error message, to see if it has been reported before.
 - If the output from the commands above does not help you to resolve the issue, please open a support ticket via the Supabase Dashboard (by clicking the "Help" button at the top right) and include all output and details about your commands.
 
 ## Advanced techniques

apps/docs/spec/cli_v1_commands.yaml

@@ -2546,10 +2546,10 @@ commands:
 
       Serve all Functions locally.
 
-      `supabase functions serve` command includes additional flags to assist developers in debugging Edge Functions via the v8 inspector protocol, allowing for debugging via Chrome DevTools, VS Code, and IntelliJ IDEA for example.
+      `supabase functions serve` command includes additional flags to assist developers in debugging Edge Functions via the v8 inspector protocol, allowing for debugging via Chrome DevTools, VS Code, and IntelliJ IDEA for example. Refer to the [docs guide](/docs/guides/functions/debugging-tools) for setup instructions.
 
       1. `--inspect`
-         * Alias of `--inspect-mode run`.
+         * Alias of `--inspect-mode brk`.
 
       2. `--inspect-mode [ run | brk | wait ]`
          * Activates the inspector capability.

examples/ai/edge-functions/supabase/functions/generate-embedding/index.ts

@@ -1,4 +1,4 @@
-/// <reference types="https://esm.sh/@supabase/functions-js/src/edge-runtime.d.ts" />
+import "https://esm.sh/@supabase/functions-js/src/edge-runtime.d.ts";
 
 import { createClient } from "npm:@supabase/supabase-js@2.42.0";
 import { Database, Tables } from "../_shared/database.types.ts";

examples/ai/edge-functions/supabase/functions/search/index.ts

@@ -1,4 +1,4 @@
-/// <reference types="https://esm.sh/@supabase/functions-js/src/edge-runtime.d.ts" />
+import "https://esm.sh/@supabase/functions-js/src/edge-runtime.d.ts";
 
 import { createClient } from "npm:@supabase/supabase-js@2.42.0";
 import { Database } from "../_shared/database.types.ts";