Visual Studio Code Wrangler Debug Configuration

[JustinGrote]

You can use this to attach and debug Cloudflare Workers written in Typescript using the new workerd local process that ships in Wrangler v3. Put it in your launch.json file for the project or your settings.json launch setting.

Warning

Until #4127 lands, you must have your repository on the C: drive on windows for this to work, otherwise it will silently fail if you have it on for instance D: when using DevDrive.

Task and Attach Method (Recommended)

//tasks.json
{
	"version": "2.0.0",
	"tasks": [
		{
			"label": "Wrangler Dev",
			"detail": "Starts your Cloudflare Worker in local development mode.",
			"type": "shell",
			"command": "pnpm wrangler dev --port 80",
			"isBackground": true,
			"problemMatcher": {
				"owner": "wrangler",
				"source": "wrangler",
				"pattern": {
					"regexp": "^(?<file>.+\\.rs):(?<line>\\d+):(?<col>\\d+):\\s+(?<message>.*)$",
					"file": 1,
					"line": 2,
					"column": 3,
					"message": 4
				},
				"background": {
					"activeOnStart": true,
					"beginsPattern": "(Starting|Reloading) local server\\.\\.\\.",
					"endsPattern": "(Ready|Updated and ready) on"
				}
			},
			"group": {
				"kind": "test",
				"isDefault": true
			},
			"icon": {
				"color": "terminal.ansiYellow",
				"id": "cloud"
			}
		}
	]
}

//launch.json

{
	"configurations": [
		{
			"name": "Wrangler Dev",
			"type": "node",
			"request": "attach",
			"preLaunchTask": "Wrangler Dev",
			"resolveSourceMapLocations": ["**", "!**/node_modules/**"] //This is key, the source maps to resolve end up located in your temp directory, and vscode by default only looks in your workspace directory. You can also set this to null or an empty array, but source maps in node_modules might get evaluated which may slow you down significantly unless you specifically want to debug those. NOTE: The latest non-released build of wrangler as of 2023-10-15 moves the temp files to the .wrangler folder in your workspace dir, so this is no longer needed as it is automatically detected correctly.
		}
	]
}

Launch Method

{
	"configurations": [
		{
			"name": "Wrangler Dev",
			"type": "node",
			"request": "launch",
			"resolveSourceMapLocations": ["**", "!**/node_modules/**"], //This is key, the source maps to resolve end up located in your temp directory, and vscode by default only looks in your workspace directory. You can also set this to null or an empty array, but source maps in node_modules might get evaluated which may slow you down significantly unless you specifically want to debug those.
			"program": "${workspaceFolder}/node_modules/wrangler/bin/wrangler.js", // You can also use the CLI directly but this is cleaner. Alternatively, you can define your start in tasks.json and make this depend on it via preLaunchTask, as long as whatever port you start the inspector on matches the port defined here for attachSimplePort
			"args": ["dev", "--inspector-port=59229"], //Force a high port to avoid conflicts with other debuggers
			"attachSimplePort": 59229, //Matches --inspector-port above
			"internalConsoleOptions": "neverOpen", // We want to see Wrangler's output usually so hide this
			"console": "integratedTerminal", // Shows the wrangler output
			"autoAttachChildProcesses": false
		},
		{
			"name": "Attach to existing Wrangler",
			"type": "node",
			"request": "attach",
			"resolveSourceMapLocations": ["**", "!**/node_modules/**"]
		}
	]
}

Now when you visit a site, you should be able to hit typescript breakpoints set in your files:

Test Debugging

For Wrangler v3, while you can use miniflare, its lack of step-through debugging is a real pain when troubleshooting. Instead, I recommend using the Task and Attach Method above to get your wrangler dev going and attached, and then adding something like this to your tests:

let baseUri: string
// Makes a request either to the test workerd (if in CI) or to wrangler dev
async function request(url: string) {
	if (!baseUri) {
		try {
			await fetch('http://127.0.0.1:8787/') //Will throw if worker dev is not running
			baseUri = 'http://127.0.0.1:8787'
		} catch (e) {
			console.table(e)
			console.log('⬆️ Wrangler Dev not running, starting temporary workerd for tests')
			const worker = await wranglerDev('src/worker.ts', {
				inspect: true,
				inspectorPort: 39929,
				experimental: {
					disableExperimentalWarning: true,
				},
			})
			baseUri = 'http://' + worker.address + ':' + worker.port
		}
	}

	return fetch(new URL(url, baseUri))
}

Basically, if you have your wrangler dev running, your tests will use that, and step through debugging will work as long as you have it running. If you don't, it will spin up a temporary workerd for that purpose.

You can also use miniflare v3, which uses workerd on the backend, if you need to test some more advanced or nuanced scenarios, however this does not have step-through debugging and does not have native typescript support (you'll have to bundle/compile yourself rather than use wranglerd)
https://github.com/cloudflare/miniflare/blob/v3.20231002.1/packages/miniflare/README.md