This page explains how to use webdev and a tool it depends on—build_runner—to build, serve, and test your web apps. The webdev package provides webdev, which wraps around the more general-purpose build_runner tool.

Usually you can use webdev instead of directly using build_runner. The only time most web app developers run build_runner is for tests.


The easiest way to get webdev is to globally install it, so that it can be in your PATH. Before you can use webdev, your web app must depend on the build_runner and build_web_compilers packages.

Installing and updating webdev

Globally install webdev using pub:

$ dart pub global activate webdev

Use the same command to update webdev. We recommend updating webdev whenever you update your Dart SDK or when webdev commands unexpectedly fail.

Depending on build_* packages

To use webdev or (in a web app context) build_runner, you must be in the root directory of a package that depends on the build_runner and build_web_compilers packages. If you’re testing the app, it must also depend on build_test.

To depend on these packages, add the following dev dependencies to your app’s pubspec.yaml file:

    # ···
    build_runner: ^2.1.0
    build_test: ^2.1.0
    build_web_compilers: ^3.0.0

As usual after pubspec.yaml changes, run dart pub get or dart pub upgrade:

$ dart pub get

Using webdev and build_runner commands

This section describes how to use the following commands:

webdev serve
Runs a development server that continuously builds a web app.
webdev build
Builds a deployable version of a web app.
build_runner test
Runs tests.

You can customize your build using build config files. For details, see the build_web_compilers package.

webdev serve

To launch a development server, which serves your app and watches for source code changes, use the following command:

webdev serve [--debug | --release] [ [<directory>[:<port>]] ... ]

By default, webdev serve compiles your app using dartdevc and serves the app at localhost:8080:

$ webdev serve  # uses dartdevc

The first dartdevc build is the slowest. After that, assets are cached on disk, and incremental builds are much faster.

To enable Dart DevTools, add the --debug flag:

$ webdev serve --debug  # enables Dart DevTools

To use dart2js instead of dartdevc, add the --release flag:

$ webdev serve --release  # uses dart2js

You can specify different directory-port configurations. For example, the following command changes the test port from the default (8081) to 8083:

$ webdev serve web test:8083 # App: 8080; tests: 8083

webdev build

Use the following command to build your app:

webdev build [--no-release] --output [<dirname>:]<dirname>

By default, the build command uses the dart2js web compiler to create a production version of your app. Add --no-release to compile with dartdevc. Using the --output option, you can control which top-level project folders are compiled and where output is written.

For example, the following command uses dart2js to compile the project’s top-level web folder into the build directory:

$ webdev build --output web:build

build_runner test

Use the build_runner test command to run your app’s component tests:

$ dart run build_runner test [build_runner options] -- -p <platform> [test options]

For example, here’s how to run all Chrome platform tests:

$ dart run build_runner test -- -p chrome

To see all available build_runner options, use the --help or -h option:

$ dart run build_runner test -h

Arguments after the empty -- argument are passed directly to the test package runner. To see all command-line options for the test package runner, use this command:

$ dart test -h

More information

For a complete list of webdev options, run webdev --help or see the webdev package.

Also see the following pages: