add docs for JS debugger in language docs #165

karthik2804 · 2026-01-16T09:39:49Z

Adds docs for using the StarlingMonkey debugger with the JavaScript SDK for Spin.

Signed-off-by: Karthik Ganeshram <kganeshr@akamai.com>

mikkelhegn · 2026-01-16T11:35:27Z

content/v3/javascript-components.md


 {{ details "Unique ID generator" "- [nanoid](https://www.npmjs.com/package/nanoid)\n- [ulidx](https://www.npmjs.com/package/ulidx)\n- [uuid](https://www.npmjs.com/package/uuid)" }} 

+## Debugging in VSCode


Given some of the limitations, should this be noted as "preview" or "experimental"?

@tschneidereit do you have any thoughts here?

mikkelhegn · 2026-01-16T11:36:43Z

content/v3/javascript-components.md

+
+#### Setup
+
+First, make sure that the extension is installed. Next verify that the templates are new enough to support debugging. This can be verified by looking `.vscode/setting.json` and verifying if something like the following is configured:


With the remark "new enough" I think it would be good to document what's the earliest version of the templates which support this.

Currently the version would be the templates that get downloaded with spin v3.5 and later. I do not believe templates themselves actually have versions. @itowlson is there a way a user can tell what version of a template they have installed?

We can document the current versions of the templates and VS Code as the setup that works here and that we support.

content/v3/javascript-components.md

Co-authored-by: Mikkel Mork Hegnhoj <12242001+mikkelhegn@users.noreply.github.com>

itowlson · 2026-01-19T19:22:29Z

content/v3/javascript-components.md


+## Debugging in VSCode
+
+The [StarlingMonkey Debugger](https://marketplace.visualstudio.com/items?itemName=BytecodeAlliance.starlingmonkey-debugger) enables debugging components built using the SDK. The debugger currently only works with the HTTP trigger and needs to be restarted for every request.


Suggested change

The [StarlingMonkey Debugger](https://marketplace.visualstudio.com/items?itemName=BytecodeAlliance.starlingmonkey-debugger) enables debugging components built using the SDK. The debugger currently only works with the HTTP trigger and needs to be restarted for every request.

You can use the [StarlingMonkey Debugger](https://marketplace.visualstudio.com/items?itemName=BytecodeAlliance.starlingmonkey-debugger) to debug JavaScript HTTP components.

We do need to mention the "restart with every request" but that needs to be a warning in the usage section rather than part of the intro material.

Or if we feel it really needs to be right up front, pull it out as a warning with context:

> The debugger is a work in progress, and has some known issues and limitations. In particular, you will need to restart it for each request.

But I still think it probably belongs with the "using" section.

itowlson · 2026-01-19T19:23:34Z

content/v3/javascript-components.md

+
+#### Setup
+
+First, make sure that the extension is installed. Next verify that the templates are new enough to support debugging. This can be verified by looking `.vscode/setting.json` and verifying if something like the following is configured:


Maybe split this into "installing the extension" (once) and "setting up the project" (each project).

itowlson · 2026-01-19T19:24:43Z

content/v3/javascript-components.md

+}
+```
+
+If it does not exist, setup the configuration using the [testcase](https://github.com/spinframework/spin-js-sdk/tree/main/test/debugger-testing/spin-ts/.vscode) as a reference. 


Suggested change

If it does not exist, setup the configuration using the [testcase](https://github.com/spinframework/spin-js-sdk/tree/main/test/debugger-testing/spin-ts/.vscode) as a reference.

If it does not exist, set up the configuration using the [test case](https://github.com/spinframework/spin-js-sdk/tree/main/test/debugger-testing/spin-ts/.vscode) as a reference.

I notice this refers to the directory, not the file. If they need copy both settings.json and launch.json, we should be explicit about that.

itowlson · 2026-01-19T19:29:00Z

content/v3/javascript-components.md

+
+#### Setup
+
+First, make sure that the extension is installed. Next verify that the templates are new enough to support debugging. This can be verified by looking `.vscode/setting.json` and verifying if something like the following is configured:


Suggested change

First, make sure that the extension is installed. Next verify that the templates are new enough to support debugging. This can be verified by looking `.vscode/setting.json` and verifying if something like the following is configured:

The first time you want to use the debugger with a project, check that debugging is set up. (Projects created with recent Spin templates will have this already, but projects created using older templates may not.) Your project is ready for debugging if it has a `.vscode/settings.json` file containing a configuration section similar to:

although I think it would need a launch.json as well, or is that magically created on demand?

itowlson · 2026-01-19T19:32:06Z

content/v3/javascript-components.md

+
+If it does not exist, setup the configuration using the [testcase](https://github.com/spinframework/spin-js-sdk/tree/main/test/debugger-testing/spin-ts/.vscode) as a reference. 
+
+Once that is setup, we need to update the configuration in `spin.toml` to build the debug component. This can be done by updating the build command in `spin.toml` to be `npm run build:debug`. We also need to add `"tcp://127.0.0.1:*"` to the list of `allowed_outbound_hosts`. 


Suggested change

Once that is setup, we need to update the configuration in `spin.toml` to build the debug component. This can be done by updating the build command in `spin.toml` to be `npm run build:debug`. We also need to add `"tcp://127.0.0.1:*"` to the list of `allowed_outbound_hosts`.

Once that is set up, we need to update the configuration in `spin.toml` to build the debug component. This can be done by setting the build command in `spin.toml` to be `npm run build:debug`. We also need to add `"tcp://127.0.0.1:*"` to the list of `allowed_outbound_hosts`.

(just trying to avoid repeating "updating")

itowlson · 2026-01-19T19:32:32Z

content/v3/javascript-components.md

+
+#### Attaching the Debugger
+
+We can start the app and attach the debugger to it using the `F5` key or using the start debugger button as show below:


Suggested change

We can start the app and attach the debugger to it using the `F5` key or using the start debugger button as show below:

We can start the app and attach the debugger to it using the `F5` key or using the Start Debugger button as show below:

itowlson · 2026-01-19T19:33:32Z

content/v3/javascript-components.md

+
+![JS debugger running](/static/image/docs/js-debugger-running.png)
+
+**Note:** that the debugger currently does not follow sourcemaps for npm dependencies as some packages may not bundle the source code in the pacakge. 


Suggested change

**Note:** that the debugger currently does not follow sourcemaps for npm dependencies as some packages may not bundle the source code in the pacakge.

**Note:** The debugger currently does not follow sourcemaps for NPM dependencies, as some packages do not bundle the source code in the package.

itowlson · 2026-01-19T19:37:19Z

content/v3/javascript-components.md

+
+**Note:** that the debugger currently does not follow sourcemaps for npm dependencies as some packages may not bundle the source code in the pacakge. 
+
 ## Caveats


I am not sure but it feels like this has come adrift from the stuff about APIs and packages that it more naturally lives with perhaps?

add docs for JS debugger in language docs

0c10c36

Signed-off-by: Karthik Ganeshram <kganeshr@akamai.com>

karthik2804 requested review from itowlson and tschneidereit January 16, 2026 09:39

add link checker exception

ac29a70

Signed-off-by: Karthik Ganeshram <kganeshr@akamai.com>

mikkelhegn suggested changes Jan 16, 2026

View reviewed changes

small fixes

9b4cf37

Co-authored-by: Mikkel Mork Hegnhoj <12242001+mikkelhegn@users.noreply.github.com>

radu-matei approved these changes Jan 19, 2026

View reviewed changes

itowlson requested changes Jan 19, 2026

View reviewed changes


		{{ details "Unique ID generator" "- [nanoid](https://www.npmjs.com/package/nanoid)\n- [ulidx](https://www.npmjs.com/package/ulidx)\n- [uuid](https://www.npmjs.com/package/uuid)" }}

		## Debugging in VSCode


		#### Setup

		First, make sure that the extension is installed. Next verify that the templates are new enough to support debugging. This can be verified by looking `.vscode/setting.json` and verifying if something like the following is configured:


		## Debugging in VSCode

		The [StarlingMonkey Debugger](https://marketplace.visualstudio.com/items?itemName=BytecodeAlliance.starlingmonkey-debugger) enables debugging components built using the SDK. The debugger currently only works with the HTTP trigger and needs to be restarted for every request.

	The [StarlingMonkey Debugger](https://marketplace.visualstudio.com/items?itemName=BytecodeAlliance.starlingmonkey-debugger) enables debugging components built using the SDK. The debugger currently only works with the HTTP trigger and needs to be restarted for every request.
	You can use the [StarlingMonkey Debugger](https://marketplace.visualstudio.com/items?itemName=BytecodeAlliance.starlingmonkey-debugger) to debug JavaScript HTTP components.

	If it does not exist, setup the configuration using the [testcase](https://github.com/spinframework/spin-js-sdk/tree/main/test/debugger-testing/spin-ts/.vscode) as a reference.
	If it does not exist, set up the configuration using the [test case](https://github.com/spinframework/spin-js-sdk/tree/main/test/debugger-testing/spin-ts/.vscode) as a reference.

	First, make sure that the extension is installed. Next verify that the templates are new enough to support debugging. This can be verified by looking `.vscode/setting.json` and verifying if something like the following is configured:
	The first time you want to use the debugger with a project, check that debugging is set up. (Projects created with recent Spin templates will have this already, but projects created using older templates may not.) Your project is ready for debugging if it has a `.vscode/settings.json` file containing a configuration section similar to:


		If it does not exist, setup the configuration using the [testcase](https://github.com/spinframework/spin-js-sdk/tree/main/test/debugger-testing/spin-ts/.vscode) as a reference.

		Once that is setup, we need to update the configuration in `spin.toml` to build the debug component. This can be done by updating the build command in `spin.toml` to be `npm run build:debug`. We also need to add `"tcp://127.0.0.1:*"` to the list of `allowed_outbound_hosts`.

	Once that is setup, we need to update the configuration in `spin.toml` to build the debug component. This can be done by updating the build command in `spin.toml` to be `npm run build:debug`. We also need to add `"tcp://127.0.0.1:*"` to the list of `allowed_outbound_hosts`.
	Once that is set up, we need to update the configuration in `spin.toml` to build the debug component. This can be done by setting the build command in `spin.toml` to be `npm run build:debug`. We also need to add `"tcp://127.0.0.1:*"` to the list of `allowed_outbound_hosts`.


		#### Attaching the Debugger

		We can start the app and attach the debugger to it using the `F5` key or using the start debugger button as show below:


		![JS debugger running](/static/image/docs/js-debugger-running.png)

		Note: that the debugger currently does not follow sourcemaps for npm dependencies as some packages may not bundle the source code in the pacakge.

	Note: that the debugger currently does not follow sourcemaps for npm dependencies as some packages may not bundle the source code in the pacakge.
	Note: The debugger currently does not follow sourcemaps for NPM dependencies, as some packages do not bundle the source code in the package.


		Note: that the debugger currently does not follow sourcemaps for npm dependencies as some packages may not bundle the source code in the pacakge.

		## Caveats

add docs for JS debugger in language docs #165

Are you sure you want to change the base?

add docs for JS debugger in language docs #165

Conversation

karthik2804 commented Jan 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

radu-matei Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

radu-matei Jan 19, 2026 •

edited

Loading