Skip to content

Debugging with Visual Studio Code

Jump to bottom
Chris Willis-Ford edited this page May 21, 2020 · 4 revisions

This page contains tips for editing and debugging scratch-gui, scratch-vm, scratch-render, and related repositories using Visual Studio Code, also known as VS Code. This page does NOT contain tips for using Visual Studio, which is a separate development environment with a similar name.

VS Code Extensions

VS Code by itself provides a very basic experience; for a more complete editing and debugging experience you'll need to install some extensions. This section lists some extensions that work well with the Scratch 3.0 repositories.

Please note that the extensions marketplace changes rapidly and this information may be out of date; this is just meant as a starting point.

Extension Name Extension ID / search term Notes
Code Spell checker streetsidesoftware.code-spell-checker
Debugger for Chrome msjsdiag.debugger-for-chrome See below for setup help
EditorConfig for VS Code editorconfig.editorconfig
EJS language support digitalbrainstem.javascript-ejs-support
ESLint dbaeumer.vscode-eslint
GitLens — Git supercharged eamodio.gitlens
GLSL Lint cadenas.vscode-glsllint Specifically for editing shaders in scratch-render
HTML CSS Support ecmel.vscode-html-css Primarily for scratch-gui
Markdown All in One yzhang.markdown-all-in-one
markdownlint davidanson.vscode-markdownlint
Node.js Modules Intellisense leizongmin.node-module-intellisense
npm eg2.vscode-npm-script
Visual Studio IntelliCode visualstudioexptteam.vscodeintellicode
XML redhat.vscode-xml
YAML redhat.vscode-yaml

Debugging in VS Code

These instructions will focus on debugging in Chrome or Chromium. It should be possible to use other browsers but you'll need different VS Code extensions and at least some of the setup instructions will be different.

Step 0: Install the basics

Goal: Install all software necessary for a basic Scratch 3.0 debugging experience.

  1. Install VS Code
  2. Install Chrome or Chromium
    • NOTE: Consider using a different browser from the one you use for regular browsing. It can occasionally be nice to restart the browser for debugging purposes and that can be annoying if it also means closing all your Stack Overflow and MDN reference tabs.
    • Download
    • Homebrew: brew cask install google-chrome or brew cask install chromium
    • Chocolatey: cinst GoogleChrome or cinst chromium
  3. In VS Code, install the "Debugger for Chrome" extension (search for msjsdiag.debugger-for-chrome)
  4. Clone the Scratch 3.0 repositories: see Getting Started

Step 1: Set up a workspace

Goal: Edit Scratch 3.0 files in VS Code.

I like to set up a multi-root workspace in VS Code so that I can see the code for multiple repositories all together. This also allows you to save the workspace files outside the repository clone. Keep in mind that you'll need to use npm link (or something similar) to make full use of a multi-root workspace. See the "linking repos" section of the Getting Started page and the associated example for more details.

Using a single-root workspace is simpler but won't make it easy to work in multiple repositories. In addition, VS code will leave some files in a .vscode subdirectory in your repository. Be careful not to include this directory when making commits that you intend to include in a PR for the official Scratch 3.0 repositories, as we generally avoid storing files for any IDE in Scratch 3.0 repositories.

Single-root workspace

  1. Pick "Open Folder..." under the "File" menu.
  2. Select your scratch-gui repository.

Further setup steps will involve editing the launch configuration for your workspace. To do this in a single-root workspace:

  1. Open the "Run" panel in the VS Code UI (looks like a bug and a triangle)
  2. Depending on the state of your workspace, one of two options will appear:
    • If you see "create a lunch.json file" then select that and, in the drop-down menu, select "Chrome"
    • Otherwise, click the "Open launch.json" button near the top (looks like a gear)

Before moving on, make sure there is a "configurations" item at the top level. That is, the minimum launch.json should look something like:

{
    "version": "0.2.0", // do not edit this version number
    "configurations": [ // this section may be empty or may have an entry with type "chrome"
    ]
}

From here on we will manipulate only the configurations section of this file.

Multi-root workspace

  1. Pick "Add Folder to Workspace..." under the "File" menu.
  2. Select your scratch-gui repository.
  3. Repeat steps 1 and 2 for each additional repository you plan to edit or debug.
    • I suggest starting with at least scratch-gui and scratch-vm.

Further setup steps will involve editing the launch configuration for your workspace. To do this in a multi-root workspace:

  1. Select the gear icon in the lower left of the VS Code window
  2. Select "Settings"
  3. Select "Workspace"
  4. Type "launch" into the search bar, which should present you with the "Launch" setting under the "Debug" section of "Features"
  5. Select "Edit in settings.json"

Before moving on, make sure there is a "launch" item at the top level with a "configurations" item underneath it. That is, the minimum workspace configuration should look something like:

{
    "folders": [
      // no need to edit the folders section
    ],
    "launch": {
        "configurations": [],  // this line is REQUIRED
        "compounds": []        // this line is optional
    }
}

From here on we will manipulate only the configurations section of this file.

Step 2: Breakpoints in scratch-gui

Goal: Hit breakpoints and inspect state using VS Code

  1. If you haven't already, start the webpack dev server by running npm start in the scratch-gui directory. It takes a while to fully start up, so let this run in a separate terminal window in the background.
  2. In your configurations section, add a "Chrome: Launch" entry. If you start typing "Chrome" you should be able to pick "Chrome: Launch" from a list then modify it, or you can just copy & paste this:
{
    "type": "chrome",
    "request": "launch",
    "name": "Launch scratch-gui in Chrome",
    "sourceMapPathOverrides": {
        "webpack://GUI/./*": "${workspaceFolder}/*", // use ${workspaceFolder:scratch-gui} in a multi-root workspace
    },
    "url": "http://localhost:8601", // note the port number!
    "webRoot": "/:" // map other / generated files to an impossible path
}
  1. Temporarily add a debugger statement somewhere in the code. I recommend putting it near the top of scratch-gui/src/lib/blocks.js:
import ScratchBlocks from 'scratch-blocks';
debugger;
  1. Pick "Start Debugging" in VS Code (select the green triangle, or the item under the "Run" menu, or press F5, or...)
  2. You should see Chrome or Chromium start up and start to load scratch-gui
  3. When the debugger statement is reached, the program should pause in VS Code and allow you to inspect local variables, the call stack, etc.
    • If this doesn't work, stop here and troubleshoot!
  4. Change the debugger; statement to something else, like console.log("hello"); or something.
  5. Use VS Code to place a breakpoint on that line 8 Pick "Start Debugging" again to verify that the breakpoint works

Congratulations! You can now use VS Code to debug Scratch 3.0 code!

Step 3: More source maps for multi-root workspaces

Goals:

  • Get VS Code to display the non-minified code for scratch-vm, and ideally all dependencies
  • Get VS Code to hit breakpoints in scratch-vm, and ideally all dependencies

Setting your workspace's sourceMapPathOverrides configuration like this is a step in the right direction:

"sourceMapPathOverrides": {
     "webpack://GUI/./*": "${workspaceFolder:scratch-gui}/*",
     "webpack://GUI/./node_modules/scratch-vm/*": "${workspaceFolder:scratch-vm}/*",
},
Clone this wiki locally