Skip to main content
Contents

build_runner

Contents

The build_runner package provides general-purpose commands for generating files, including testing the generated files or serving both source and generated files. This page explains how to use build_runner. To learn how to use build_runner with a specific package, see the documentation for that package.

The build_runner commands work with builders—packages that use the Dart build system to generate output files from input files. For example, the json_serializable and built_value_generator packages define builders that generate Dart code.

Although the Dart build system is a good alternative to reflection (which has performance issues) and macros (which Dart's compilers don't support), it can do more than just read and write Dart code. For example, the sass_builder package implements a builder that generates .css files from .scss and .sass files.

Setting up build_runner

#

To use build_runner, add a dev dependency on build_runner to your app's pubspec:

yaml
dev_dependencies:
  # ···
  build_runner: ^2.4.15
  build_test: ^2.2.3

Depending on build_test is optional; do it if you'll be testing your code.

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

dart pub get

Using built-in commands

#

The following is an example of using the build_runner build command:

# From a directory that contains a pubspec.yaml file:
dart run build_runner build

The build_runner package includes the following commands:

build
Performs a one-time build.
serve
Runs a development server. Instead of directly using this command, you can use webdev serve, which has convenient default behavior.
test
Runs tests.
watch
Launches a build server that watches for edits to input files. Responds to changes by performing incremental rebuilds.

More information

#

If you're working on web-specific code, see the webdev page.

For details on using build_runner, see the following:

Unless stated otherwise, the documentation on this site reflects Dart 3.8.0. Page last updated on 2025-05-19. View source or report an issue.