webdev and build_runner

The webdev and build_runner tools are command-line interfaces (CLIs) that you can use to build, serve, and test 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 use webdev is to globally install it, so that it can be in your PATH. The build_runner tool can’t be globally installed; to run it, you need pub run.

Before you can use either tool, your web app must depend on the build_runner and build_web_compilers packages.

Installing and updating webdev

Globally install webdev using pub:

$ 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: ^1.0.0
  build_test: ^0.10.2
  build_web_compilers: ^0.4.0

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

$ 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 README.

webdev serve

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

webdev serve [--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 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 the dartdevc to compile the project’s top-level web folder into the build directory:

$ webdev build --no-release --output web:build

build_runner test

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

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

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

$ pub run build_runner test -- -p chrome

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

$ pub 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:

$ pub run test -h

More information

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

Also see the following pages: