Flutter 3.29 and Dart 3.7 dropped in February 2025, 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 and unless you explicitly opt-out, you'll get a ton of formatting changes in your codebase. This article guides you through the new changes and all the configuration options, so you can handle things smoothly.
Let's dive in!
Update: Dart 3.8 (part of Flutter 3.32) adds a new formatter option to preserve trailing commas. This is significant because it means you can upgrade your SDK but still opt-out if you don't like the new style. More on this below.
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 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 or above, 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_widthis 80 (default), everything will align without 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 About the Updated Formatter in Dart 3.8?
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.
After more discussions, the Dart team agreed to add a new formatter option in Dart 3.8 to preserve trailing commas.
This means you can upgrade to Dart 3.8:
# pubspec.yaml
environment:
sdk: ^3.8.0
Then, you have to choose between two options:
1. Preserve trailing commas
Enable this option in your analysis_options.yaml file:
# analysis_options.yaml
formatter:
trailing_commas: preserve
Effectively, this disables the new formatter behaviour and gives you back control over trailing commas.
2. Don't preserve trailing commas (default formatting style)
As discussed above, the new formatting style will strip trailing commas on code that fits within the page width, so expect a large diff in your codebase.
To handle this smoothly, follow these steps:
- Set a custom
page_widthinanalysis_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_runneragain 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.32 is brand new—bugs may still surface. If you're not in a rush, consider waiting for a hotfix release before upgrading.
Additional Resources
All the configuration options are documented here:
Here's the original proposal and discussion about the new formatter:
