Debug a transpiled ActionScript project in Visual Studio Code with Mozilla Firefox

1. Create a new ActionScript project targeting Apache Royale or HTML and JavaScript without a framework.

2. In your project's asconfig.json, specify the source-map compiler option.

   "compilerOptions": {
   	"source-map": true
   }

   This will allow you to add breakpoints and perform other debugging tasks using the original .as or .mxml files instead of the generated .js files.

3. Install the Debugger for Firefox extension for Visual Studio Code.

4. Create a directory named .vscode, if it doesn't already exist.

5. In the .vscode directory, create a file named launch.json.

   • To load from a web server, add the following content to launch.json:

      {
      	"version": "0.2.0",
      	"configurations": [
      		{
      			"name": "Launch Firefox (localhost)",
      			"type": "firefox",
      			"request": "launch",
      			"url": "http://localhost:8080/index.html",
      			"webRoot": "${workspaceRoot}"
      		}
      	]
      }

     Customize the url field to point to the correct URL for your web server.

   • To load a local HTML file, add the following content to launch.json:

      {
      	"version": "0.2.0",
      	"configurations": [
      		{
      			"name": "Launch Firefox (index.html)",
      			"type": "firefox",
      			"request": "launch",
      			"url": "file:///${workspaceRoot}/bin/js-debug/index.html",
      			"webRoot": "${workspaceRoot}/bin/js-debug"
      		}
      	]
      }

6. Run the build task with Ctrl+Shift+B (or Command+Shift+B on macOS).

7. Open Visual Studio Code's Run menu, and select Start Debugging. Alternatively, use the F5 keyboard shortcut to start debugging.

Build automatically before debugging

Instead of building manually with Ctrl+Shift+B, you can configure launch.json to build your project automatically when start debugging in Visual Studio Code. By setting the preLaunchTask field in launch.json to the name of one of your workspace's tasks, it will automatically run that task before the debugger is launched.

Warning: If you're compiling debug builds using the Quick Compile & Debug command, DO NOT use preLaunchTask. It will cause your project to build twice before starting the debugger, which won't be very "quick" at all! 😄

If you have a default build task configured, the preLaunchTask field in launch.json should contain the ${defaultBuildTask} token:

"preLaunchTask": "${defaultBuildTask}"

If you prefer, you can use the exact name of any of the built-in tasks provided by the ActionScript & MXML extension:

"preLaunchTask": "ActionScript: compile debug - asconfig.json"

You can find the complete list of tasks that are available in your workspace when you go to the Terminal menu and choose Run Task....

Troubleshooting

Debugger will not stop at breakpoints on startup

In Firefox, the debugger may not stop at certain breakpoints that are added during your app's initialization. However, you will find that breakpoints that are triggered later (such as those added inside mouse event listeners) work correctly.

This is a limitation of the Firefox debug protocol. The JavaScript starts executing before the debugger can connect, so these breakpoints are essentially ignored. However, there is a workaround. You may add a debugger statement before the main class is instantiated in your HTML template file:

<script>
	debugger;
	new MainClass();
</script>

The debugger will automatically pause at this line. Press the green continue button in the debugger controls, or use the F5 keyboard shortcut, to resume debugging and access the breakpoints that previously didn't work.

Note: The debugger statement cannot be used in ActionScript. It must be added inside the JavaScript <script> tag on the HTML page.

Further Reading

• Debugging in Visual Studio Code (visualstudio.com)
• Debugger for Firefox extension (visualstudio.com)