The dart2js tool provides hints for improving your Dart code and removing
unused code. You can get these hints for all kinds of code—even command-line
apps. Also see dartanalyzer,
which performs a similar analysis but, as of 1.0,
has a different implementation.

Support for new language features:
dart2js doesn’t currently support async functions or await expressions.
However, you can try out asynchrony in your Dart web app by using the
async-await pub transformer
when you build the JavaScript version of your app.
For more information on this feature, see
Asynchrony support.

To use dart2js on code that includes enumerated types, opt in by specifying
the --enable-enum flag.

This page tells you how to use dart2js on the command line. It also give tips
on debugging the JavaScript that dart2js generates.

Basic usage

Here’s an example of compiling a Dart file to JavaScript:

dart2js --out=test.js test.dart

This command produces a file that contains the JavaScript equivalent of your
Dart code. It also produces a source map, which can help you debug the
JavaScript version of the app more easily.

Options

Generate the output into <file>. If not specified,
the output goes in a file named out.js.

-c or --checked

Insert runtime type checks, and enable assertions (checked mode).

-m or --minify

Generate minified output.

-h or --help

Display help. (Use -vh for information about all options.)

Some other handy options include:

-p <path> or --package-root=<path>

Specify where to find “package:” imports.

-D<flag>=<value>

Define an environment variable.

--enable-enum

Enable support for enumerated types. For more information on this
language feature, see
Enumerated types.

--version

Display version information for dart2js.

The following options help you control the output of dart2js:

--suppress-warnings

Don’t display warnings.

--suppress-hints

Don’t display hints.

--terse

Emit diagnostics, but don’t suggest how to get rid of the diagnosed problems.

-v or --verbose

Display lots of information.

The following options control the analysis that dart2js performs on Dart code:

--analyze-all

Analyze even the code that isn’t reachable from main(). This option
is useful for finding errors in libraries, but using it can result in
bigger and slower output.

-analyze-only

Analyze the code, but don’t generate code.

--analyze-signatures-only

Like --analyze-only, but skip analysis of method bodies and field
initializers.

--enable-diagnostic-colors

Add colors to diagnostic messages.

--show-package-warnings

Show warnings and hints generated from packages.

--csp

If true, disables dynamic generation of code in the generated output.
This is necessary to satisfy CSP restrictions
(see W3C Content Security Policy).
The default is false.

Version note: Before Dart 1.8, the CSP version of JavaScript was generated
automatically, and saved with the extension .precompiled.js.
As of the 1.8 release, you must specify the CSP format using the --csp flag,
and the resulting file is saved with the normal .js extension.

--categories=Server

Use with --analyze-only to analyze a command-line app. The default
category is Client, which tells dart2js to expect a web app. This option is only for dart2dart.

--dump-info

Generates an out.info.json file with information about the generated code.
You can inspect the generated file with the viewer.

--output-type=dart

Output Dart code instead of JavaScript. If you are looking for dart2dart, use this option.

Helping dart2js generate better code

You can do a couple of things to improve the code that dart2js generates:

Write your code in a way that makes type inference easier.

Once you’re ready to deploy your app, use the dart2js --minify option to
reduce code size.

Note:
Don’t worry about the size of your app’s included libraries. The dart2js tool
performs tree shaking to omit unused classes, functions, methods, and so on.
Just import the libraries you need, and let dart2js get rid of what you don’t
need.

Follow these practices to help dart2js do better type inference, so it can generate smaller and faster JavaScript code:

Avoid using the dart:mirrors library, directly or indirectly. If you must
use it, provide @MirrorsUsed annotations.

Don’t use Function.apply().

Don’t override noSuchMethod().

Avoid setting variables to null.

Be consistent with the types of arguments you pass into each function or
method.

Debugging

This section gives tips for debugging dart2js-produced code in Chrome, Firefox,
and Safari. Debugging the JavaScript produced by dart2js is easiest in
browsers such as Chrome that support source maps.

Whichever browser you use, you should enable pausing on at least
uncaught exceptions, and perhaps on all exceptions. For frameworks such
as dart:isolate and dart:async that wrap user code in try-catch, we
recommend pausing on all exceptions.