Getting started with
build_runner, you need a 2.x version of
the Dart SDK.
If you have issues using
build_runner, see the
Troubleshooting section, below.
build_runneras a development server
- Creating an output directory
- Using other
- Switching to Dart2JS
- Compatibility with other packages
build_runner as a development server
Edit your package's pubspec.yaml file, adding dev dependencies on build_runner and build_web_compilers:
... environment: sdk: '>=2.0.0 <3.0.0' ... dev_dependencies: build_runner: ^1.0.0 build_web_compilers: ^0.4.0
Get package dependencies:
Start the server:
pub run build_runner serve
serve command runs, every change you save triggers a rebuild.
The first build is the slowest. After that, assets are cached on disk and incremental builds are faster.
Creating an output directory
--output <directory name> to write files into a merged output
directory with file paths that match internally referenced URIs. This can be
used with the
serve commands. This directory can also
used with a different server if the
serve command is insufficient.
To output only part of the package, for example to output only the
--output web:<directory name>.
In addition to serve you can use:
build: Runs a single build and exits. This is most useful if your build also generates output to your source directory. With
--output <dirname>this also creates a merged output directory with all sources and generated assets.
buildbut reruns after file changes. With
--output <dirname>the merged output directory will be kept up to date with changes. This can be used to keep the outputs updated for use with another filed-based development server.
test: Creates an output directory and runs
pub run testwithin it. This command requires a dev dependency on
Switching to dart2js
build_web_compilers uses dartdevc. To switch to dart2js, pass
pub run build_runner build (or
serve). Pass args to dart2js
by creating a
targets: $default: builders: build_web_compilers|entrypoint: options: dart2js_args: - --minify - --fast-startup
Compatibility with other packages
Upgrading from transformers
build_runner can only run Builders that are published with a
file; it can't use legacy
Transformers. If your pubspec lists transformers,
switch to a version of the transformer-containing package that has a
Upgrading from manual
Older versions of
build_runner were designed to run with manually written
build scripts referencing the Builders available in the local package or in
dependencies. This pattern can still be used when customization is needed
build.yaml, but we recommend using the generated build script
pub run build_runner, because it will be kept up to date with changes
in the build packages. If your pubspec lists transformers, switch to a version of
the builder-containing package that has a
When the development process included
dartium HTML files typically referenced
main.dart and used a transformer to rewrite to
main.dart.js for deployment.
script tags should be manually rewritten to always reference
*.dart.js with a
browser dependencies can be dropped.
Diagnosing build times
build_runner has no versions that match...
Make sure you're using a 2.x SDK.
Check the versions of the packages that your app depends on. They should all be compatible with a 2.x SDK.
Too many open files
If you see a FileSystemException, saying the directory listing failed due to too many open files, you might need to increase the OS limits.
For details, see https://github.com/dart-lang/build/issues/857.