Debugging Netlify functions in VSCode and Cursor with the new ESModule format

Support
,
1

Debugging Breakpoints Not Working with New Netlify Function Syntax (ESM/Edge Runtime)

Issue: VS Code breakpoints are not hitting when using the new Netlify function syntax, but work fine with the legacy format.

Problem Description

I’m developing a Netlify function using TypeScript and the new function syntax (ESM modules with Edge Runtime support), but I cannot get VS Code breakpoints to work during local development with netlify dev. The breakpoints work perfectly when I use the legacy function format.

In this specific case, I’m attempting to modify netlify’s serverless-mcp-server so that I can debug it in Cursor/VSCode. (Aside: It would be helpful to have the launch.json pre-configured in the sample projects).

Current Setup

Function using new syntax (serverless-mcp-server.ts):

// This format does NOT work with breakpoints
const handler = async (req: Request) => {
  // Breakpoints here are ignored
  try {
    if (req.method === "POST") {
      return handleMCPPost(req);
    }
    // ... rest of handler
  } catch (error) {
    console.error("MCP error:", error);
  }
};

Function using legacy syntax (mcp.ts):

// This format DOES work with breakpoints
import { Handler } from "@netlify/functions";

const handler: Handler = async (event) => {
  // Breakpoints here work correctly
  return {
    statusCode: 200,
    body: JSON.stringify({ message: "Hello, world!" }),
  };
};

export { handler };

VS Code Launch Configuration

My current .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "netlify dev",
            "type": "node",
            "request": "launch",
            "skipFiles": ["<node_internals>/**"],
            "outFiles": ["${workspaceFolder}/.netlify/functions-serve/**/*.{js,mjs}"],
            "program": "${workspaceFolder}/node_modules/.bin/netlify",
            "args": ["dev"],
            "console": "integratedTerminal",
            "env": {
                "BROWSER": "none"
            }
        }
    ]
}

(Note that this “.mjs” addition was adapted from the official launch.json example on Netlify’s site)

Key Issues I’m having

  1. Output File Format: The new function syntax generates .mjs files, but the current VS Code documentation and examples only reference .js files in the outFiles pattern.

  2. Source Map Issues: When using the new syntax, source maps don’t seem to be properly generated or linked, preventing breakpoints from resolving correctly.

  3. Function Export Format: The new syntax uses a different export pattern that may not be compatible with the current debugging setup.

Configuration Details

  • Netlify CLI: v22.1.3
  • @netlify/functions: v3.1.10
  • TypeScript: v5.8.3
  • Node.js: Using ESM modules ("type": "module" in package.json)
  • Bundler: esbuild (configured in netlify.toml)

Questions for the Community

  1. Has anyone successfully configured VS Code debugging for the new Netlify function syntax?

  2. Are there specific outFiles patterns or source map configurations needed for .mjs output files?

  3. Is there a recommended VS Code launch configuration for debugging ESM-based Netlify functions?

  4. Are there any known limitations or workarounds for debugging the new function format?

Workaround

Currently, I’m forced to use the legacy function format for development and debugging, then convert to the new syntax for production. This is not ideal for maintaining code consistency and I am not confident I can get it working with the MCP server (since it requires mapping the Event object to the Node Request automatically supplied in the new format)

Expected Behavior

Breakpoints should work regardless of which function syntax is used, as both are officially supported by Netlify.

Thank you! I am greatly appreciative. Netlify is wonderful.