Debugging Dart web apps

You can use Chrome DevTools and the Dart development compiler (dartdevc) to debug your Dart web app.

This page walks you through using Dart with Chrome DevTools, with special attention for setup and Dart-specific considerations. For general information on debugging with Chrome DevTools, see the JavaScript debugging get started guide and reference.

Overview

  • To serve your app, use webdev serve (which uses dartdevc), either at the command line or through your IDE.
  • To see Dart types in Chrome DevTools, enable custom formatters.
  • You can’t use Dart code in the Chrome DevTools console (someProperty), but sometimes you can use JavaScript code that’s close (this.someProperty).
  • If you have trouble setting a breakpoint in Dart code, try disabling and re-enabling source maps.

Debugging web apps - 图1

Getting started with Chrome DevTools

The Dart development compiler (dartdevc) has built-in support for source maps and for custom formatting of Dart objects.

Prerequisites

To use the Chrome DevTools to debug with dartdevc, you need the following software:

Walkthrough

This section leads you through the basics of using Chrome DevTools to debug a web app. If you already have an app that’s ready to debug, you can skip creating the test app (step 1), but you’ll need to adjust the instructions to match your app.

  1. Optional: Create an app named test_app that uses Stagehand’s web-angular template.

    • If you’re using the command line, here’s how to create the app using Stagehand:

      1. $ mkdir test_app
      2. $ cd test_app
      3. $ stagehand web-angular
      4. $ pub get

    • If you’re using a Dart IDE or editor, create an AngularDart web app and name it test_app. You might see the description A web app with material design components.

  2. Compile and serve the app with dartdevc, using either your IDE or webdev at the command line.

    1. $ webdev serve

    Note: The first dartdevc compilation takes the longest, because the entire app must be compiled. After that, refreshes are much faster.

  3. Open the app in a Chrome browser window.
    For example, if you use webdev serve with no arguments, open localhost:8080.

  4. Open DevTools: Press Control+Shift+I (or Command+Option+I on Mac).

  5. Enable custom formatters, so that you can see Dart types in Chrome DevTools.

  6. Select the Sources tab.

  7. In the File Navigator pane, select Page and navigate to the Dart file for a nontrivial component.
    For example, navigate to packages/test_app/src/todo_list/todo_list_component.dart.

  8. Set a line-of-code breakpoint in a method that’s called in response to a user event.
    For example, break at the top of the add() method by clicking the line number 36.

  9. In the app’s UI, trigger the event that causes the method call. Execution stops at the breakpoint.
    For example, type something into a text field and press Enter.

  10. In the Code Editor pane, mouse over the properties. You can see their Dart runtime types and values.
    For example, in the add() method, items is a List<String> with a length of 0.

    Troubleshooting: If you see Array instead of List, then custom formatters aren’t on. Enable them.

  11. Look at the Call Stack and Scope panes, which are in the JavaScript Debugging pane. Under Scope, look at the type and value of the local variable this.

  12. Resume script execution, and trigger the event again. Execution pauses again.

  13. If the console isn’t visible, press Esc.

  14. In the console, try viewing a property of the component.

    For example, try to view the items object:

    • Enter items. It doesn’t work because JavaScript requires a this. prefix.

    • Enter this.items. This works because the JavaScript object has the same name as the Dart object. Thanks to custom formatters, you can see the Dart type and value.

    • Enter this.items[0]. This works because Dart lists map to JavaScript arrays.

    • Enter this.items.first. This doesn’t work, because unlike the Dart List class, JavaScript arrays don’t have a first property.

  15. Try other DevTools features.

Changing DevTools settings

This section covers settings that you might need to change as you debug your app.

Enabling custom formatters

To see Dart types in Chrome DevTools, you need to enable custom formatters.

  1. From the DevTools Customize and control DevTools ⋮ menu, choose Settings. Or press F1.
  2. Select Enable custom formatters, which is under the Console heading in the Preferences settings.
  3. Close Settings: Press Esc or click the x at the upper right.

Disabling and re-enabling source maps

Chrome DevTools enables source maps, by default. You might want to temporarily disable source maps so that you can see the generated JavaScript code.

  1. From the DevTools Customize and control DevTools ⋮ menu, choose Settings. Or press F1.
  2. Find the Enable JavaScript source maps checkbox, which is under the Sources heading in the Preferences settings.
    • To display only JavaScript code, clear Enable JavaScript source maps.
    • To display Dart code (when available), select Enable JavaScript source maps.
  3. Close Settings: Press Esc or click the x at the upper right.

Getting webdev and stagehand

If you’re using the command line instead of an IDE or Dart-enabled editor, then you need the webdev tool. To use the command line to create apps from standard templates, you also need the stagehand tool. Use pub to get these tools:

  1. $ pub global activate webdev
  2. $ pub global activate stagehand

If your PATH environment variable is set up correctly, you can now use these tools at the command line:

  1. $ webdev --help
  2. A tool to develop Dart web projects.
  3. ...

For information on setting PATH, see the pub global documentation.

Whenever you update the Dart SDK or want to get the latest Stagehand templates, update the tools by activating them again:

  1. $ pub global activate webdev     # update webdev
  2. $ pub global activate stagehand  # update stagehand