# build_runner

> A tool for building, testing, and running Dart code.



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.

:::note
If you're a web developer, use the [`webdev` tool][webdev] to
build and serve web apps.
:::

The build_runner commands work with _builders_—packages
that use the [Dart build system][build]
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:

<?code-excerpt "build_runner_usage/pubspec.yaml" from="dev_dependencies" to="build_test" replace="/args.*/# ···/g"?>
```yaml
dev_dependencies:
  # ···
  build_runner: ^2.8.0
  build_test: ^3.4.0
```

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`:

```console
$ dart pub get
```

## Using built-in commands

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

```console
$ # 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`,][webdev serve]
  which has convenient default behavior.

test
: Runs [tests.][tests]

watch
: Launches a build server that watches for edits to input files.
  Responds to changes by performing incremental rebuilds.


## More information

* [webdev][] guide (use if you're working on web-specific code)
* [build_runner][] guide
* [packages with the `build_runner` dependency][]
* [packages with the `build` dependency][]

[build]: https://github.com/dart-lang/build
[build_runner]: https://pub.dev/packages/build_runner
[built_value_generator]: https://pub.dev/packages/built_value_generator
[dev dependency]: /tools/pub/dependencies#dev-dependencies
[json_serializable]: https://pub.dev/packages/json_serializable
[packages with the `build` dependency]: https://pub.dev/packages?q=dependency%3Abuild
[packages with the `build_runner` dependency]: https://pub.dev/packages?q=dependency%3Abuild_runner
[sass_builder]: https://pub.dev/packages/sass_builder
[tests]: /tools/testing
[webdev]: /tools/webdev
[webdev serve]: /tools/webdev#serve

