There's a New Formatting Style in Dart 3.7 (Here's What It Means for You)

Flutter 3.29 and Dart 3.7 just dropped, bringing a bunch of new features and improvements.

While some changes might not impact you immediately, one update will affect every Flutter developer: the new Dart formatter.

This change is big—expect a ton of formatting updates in your codebase. I decided to share this article right away, so you can handle it smoothly.

Let's dive in!

How Did The Old Formatter Work?

Before Dart 3.7, you had control over trailing commas. Consider this widget constructor:

Here's how the old formatter behaved:

• Add a trailing comma → formatter splits it into multiple lines.
• Remove the trailing comma → formatter inlines it (if it fits within the page width).

While consistent, this approach required you to decide whether to add or remove trailing commas for all parameter lists and widgets in your codebase (and argue about it during code reviews 😞).

To fix this, Dart 3.7 introduces a new formatting style.

How Does The New Formatter Work?

Now, the formatter automatically decides whether to add or remove trailing commas.

• If a parameter list fits within the max page width, the formatter removes trailing commas and keeps it inline:

• If a parameter list exceeds the max page width, the formatter adds a trailing comma and splits it into multiple lines:

Summary: Old vs New Formatter

• Old formatter
  • Add trailing comma → split into multiple lines
  • Remove trailing comma → inline code

• New formatter
  • Code fits on one line → remove trailing comma and inline code
  • Code exceeds page width → add trailing comma and split into multiple lines

What Does This Mean for You?

If you upgrade to Flutter 3.29 but your pubspec.yaml still uses Dart 3.6 or below, nothing changes yet:

environment:
  sdk: ^3.6.0

But as soon as you explicitly upgrade to Dart 3.7, the new formatter kicks in:

environment:
  sdk: ^3.7.0

And when that happens... expect a massive diff in your codebase.

⚠️ Important: Formatting Applies on Save

As soon as you save a file, the new formatting style applies, leading to large diffs:

To avoid chaos, apply the new formatter across your entire codebase in one go:

# Run from the root of your project
dart format .

This ensures all formatting changes are applied consistently. I recommend to push this as a single PR and merge it before making other changes:

# Push all changes at once
git add .
git commit -m "Apply the new formatter"
git push

For reference, when I applied the new formatter to my Flutter Tips App, I ended up with a PR with 1200+ changes, which is about 25% of the total line count:

What About Page Width?

Let's recall that the new formatter decides how to format the code based on the maximum page width (a.k.a line length).

This is configurable in your analysis_options.yaml file:

formatter:
  page_width: 120

Changing this and running dart format again will reformat your entire codebase accordingly.

Bottom line: Pick a page width that works for your project and team, and stick with it. 👍

What About Code-Generated Files?

When you run dart format ., it applies to all Dart files in your project—including generated files.

But there's a catch: build_runner doesn’t respect your page_width setting. Most code generators format output with a fixed 80-character line width, which means generated files may not match your project's formatting.

What this means for you:

• If your page_width is 80 (default), everything will align—no issues.
• If you use a custom page width, generated files will revert to 80-character line breaks whenever you run build_runner.

This isn’t a major problem, since you only need to run the formatter once for the entire project (as suggested above).

Future Improvement: According to this comment, a future Dart formatter update will allow excluding specific files from formatting, which could help with this issue.

What's my take on the new formatter?

When the new formatter was first discussed in 2023, some raised concerns about inconsistent formatting because line breaks don't respect the semantic meaning of the code.

But the vast majority of the comments were positive, and I agree with them.

Honestly? Life’s too short to quabble about formatting. I'm very happy that a tool can enforce this for me, and I bet this will be a velocity boost for many developers and teams.

Recap: What You Need to Do

• Upgrade to Dart 3.7 in pubspec.yaml:

# pubspec.yaml
environment:
  sdk: ^3.7.0

• Set page_width in analysis_options.yaml (optional but recommended):

# analysis_options.yaml
formatter:
  page_width: 120

• Apply the formatter to your entire codebase:

# Run from the root of your project
dart format .

• Run build_runner again to update the generated files:

# Update code-generated files
dart run build_runner watch -d

• Push the changes as a single PR, then merge it before continuing development.

# Push all changes at once
git add .
git commit -m "Apply the new formatter"
git push

While the new formatter is safe to use, Flutter 3.29 is brand new—bugs may still surface. If you're not in a rush, consider waiting for a hotfix release before upgrading.

Additional Resources

You can read the original proposal and discussion about the new formatter here:

• New tall style: Automated trailing commas and other formatting changes