You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Investigate dart fix or other options for material/cupertino migration #172935
This issue tracks the investigation into providing a custom fix with the existing dart fix command, or another tool, to automate the migration to the new, standalone design system packages.
To make the transition to the new packages as seamless as possible, we want to provide developers with automated tooling. Leveraging the existing dart fix infrastructure is the ideal way to handle the necessary code changes and significantly reduce migration friction for existing projects.
A custom fix would need to handle a one-time update for developers. The primary changes include:
Adding the new material and cupertino package dependencies to pubspec.yaml.
Updating import statements. This is crucial because the new packages will no longer re-export the entire widgets library, requiring an explicit import package:flutter/widgets.dart; in many cases.
From what I know at this point, yes, it looks like something we ought to be able to do using data-driven fixes. If the data-driven fixes support isn't up to the task today then we ought to be able to extend it to handle the new cases.
One possible option to explore is to add a 'library' element to the fix support so that we can write a transform of the form 'replaced library material from package flutter with library material from package material'. It would be much less work for the framework team (than adding a transform for every deprecated class), and would probably give us an easier way to support the pubspec.yaml edits that we also want to be able to make.
This issue is marked P1 but has had no recent status updates.
The P1 label indicates high-priority issues that are at the top of the work list. This is the highest priority level a bug can have if it isn't affecting a top-tier customer or breaking the build. Bugs marked P1 are generally actively being worked on unless the assignee is dealing with a P0 bug (or another P1 bug). Issues at this level should be resolved in a matter of months and should have monthly updates on GitHub.
Please consider where this bug really falls in our current priorities, and label it or assign it accordingly. This allows people to have a clearer picture of what work is actually planned. Thanks!
This is not meant to be a final implementation. The goal is to make the
practical migration cases concrete before deciding how much should live in dart fix versus a separate migration tool.
What the prototype reports
Candidate pubspec.yaml dependency additions for material_ui and cupertino_ui.
Candidate URI rewrites from Flutter SDK design imports to standalone package
imports.
Likely explicit Flutter framework imports, especially package:flutter/widgets.dart.
Manual-review cases for public exports, combinators, prefixes, and part
files.
Changing them can affect downstream package APIs, not just the current package.
Prefixed imports
Prefixed design imports are mechanically easy to URI-rewrite:
import'package:flutter/material.dart'as material;
However, they do not solve unprefixed framework symbol usage elsewhere in the
same file.
part files
The design import can live in the library file while the framework symbol usage
appears in a part file, so a migration pass needs to consider the whole
library unit rather than only one file at a time.
Question for maintainers
Does this audit direction seem useful for this issue?
If so, I can turn it into a targeted Flutter tool/framework PR after guidance on:
where this should live;
whether it should be a dart fix, Flutter tool command, or separate migration
helper;
which cases should be automatically fixed versus reported for manual review.
Thanks for helping us think this through so we can get this right!
... before deciding how much should live in dart fix versus a separate migration tool.
From a UX design perspective, it's important for every tool to be well defined. That is, every tool should have one thing it does, and there shouldn't be multiple tools that do the same thing. The dart fix tool is focused on fixing problems (diagnostics) in Dart code, which would include most of the items you listed. There is, of course, more to migrating a Flutter app than just fixing diagnostics, and the other pieces should be done by one or more different tools, so the question is still a good one.
@kallentu has been thinking about a possible migration tool, though it's scope might be too narrow at this point to handle some of these cases. (Intentionally narrow in order to make the task more manageable, not because we haven't thought about some of these other aspects.)
Candidate pubspec.yaml dependency additions for material_ui and cupertino_ui.
Updating the pubspec.yaml file when a fix required referencing a previously unreferenced package is already part of what dart fix is capable of doing. And I believe that with the changes @keertip has made to the data-driven fix support, that should already be covered.
Candidate URI rewrites from Flutter SDK design imports to standalone package imports.
That's also a pre-existing feature in dart fix, and we've tested to ensure that it works for this use case as well.
Likely explicit Flutter framework imports, especially package:flutter/widgets.dart.
That's an interesting case, and I don't think we have that one covered yet. When there's an import of a deprecated library a diagnostic will be generated for it, but I don't think we have any data in the fix data file to capture which libraries should be imported in order to get implicitly imported names.
@keertip We should test this and consider ways to capture this data if we can't already handle the case.
Manual-review cases for public exports ...
I believe that there's already a diagnostic when one library attempts to export a deprecated library, so assuming that the replaced libraries will be marked as being deprecated the tool will have a signal. This might be a slight variation on the import question above; that is, we might need similar information in order to fix the exports so that the same names are being exported as before.
... combinators ...
Good point. I'm not sure whether dart fix will currently add combinators when replacing one import (that used combinators) with another. We should test this case.
... prefixes ...
But I do believe that the tool will correctly add a prefix to an import when the name being imported is qualified by an import prefix.
... and part files.
I believe that the fixes already handle references in part files by updating the imports in the root of the library.
... which cases should be automatically fixed versus reported for manual review.
The ideal, of course, is for everything that can be automated to be automated. The question is: are there changes that we can't know how to automate? I don't see anything here that clearly makes me think that it should need to manually be done, but I might be missing something.
Thanks, that makes sense. I’ll narrow the prototype/follow-up around validating the existing data-driven fix behavior rather than positioning this as a separate migration tool.
Based on your notes, the main cases worth testing seem to be:
whether implicit framework symbols from material.dart / cupertino.dart can cause dart fix to add explicit imports such as package:flutter/widgets.dart;
whether exports of deprecated design libraries can preserve the exported API surface;
whether imports with show / hide combinators are rewritten or split correctly.
I’ll update the prototype/readme to treat pubspec dependency additions, simple URI rewrites, prefixes, and part-file references as expected existing dart fix capabilities unless testing shows otherwise.
an audit script for finding Material/Cupertino migration surfaces
a full migration supplement for cases that are not covered by a simple library rewrite alone
a pre-merge validation script that creates a temporary fixture app, injects proposed library-level fix data into a copied Dart SDK, runs dart fix, runs the supplement, and compares the result with expected output
Validation command used:
dart run tool/run_premerge_dart_fix_validation.dart
I ran this against a copied Dart SDK to avoid modifying my local Flutter SDK. The validation passed:
Pre-merge dart fix validation passed.
The covered cases are:
simple package:flutter/material.dart and package:flutter/cupertino.dart library rewrites
adding explicit package:flutter/widgets.dart imports for framework symbols previously coming through material.dart / cupertino.dart
splitting mixed show combinators
preserving public export surfaces
preserving prefixed imports
handling framework symbol usage from part files
adding material_ui / cupertino_ui dependencies to pubspec.yaml
One important note: my local Dart SDK is 3.11.5 from April 15, 2026, so it may not include the recently landed Dart SDK support from dart-lang/sdk#62849. In that environment, dart fix alone did not apply the full migration; the local supplement completed the remaining cases.
Given that dart-lang/sdk#62849 has now landed, would the preferred next step be:
opening a Flutter PR that adds real fix-data coverage/tests for this migration once the updated Dart SDK support is available in Flutter, or
continuing to use this PoC to validate the remaining edge cases first?
Happy to turn this into a targeted upstream PR once the expected location and scope are clear.
Opened the migration-tooling follow-up in #186658. It is now based on master, has local validation listed in the PR body, and has no unresolved review threads. Current remaining blockers are review, CICD label, and Google testing.
This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.
Activity
a-siva commentedon Jul 30, 2025
//cc @srawlins @pq is this something that is feasible in
dart fixPiinks commentedon Jul 30, 2025
Thank @a-siva! Also touched base with @bwilkerson. I am putting together a doc of potential things to look at together. :)
srawlins commentedon Jul 30, 2025
Yeah this sounds like it might be a data-driven migration, if it's possible. Best contacts are @bwilkerson and @keertip
bwilkerson commentedon Aug 12, 2025
From what I know at this point, yes, it looks like something we ought to be able to do using data-driven fixes. If the data-driven fixes support isn't up to the task today then we ought to be able to extend it to handle the new cases.
bwilkerson commentedon Aug 14, 2025
One possible option to explore is to add a 'library' element to the fix support so that we can write a transform of the form 'replaced library material from package flutter with library material from package material'. It would be much less work for the framework team (than adding a transform for every deprecated class), and would probably give us an easier way to support the
pubspec.yamledits that we also want to be able to make.flutter-triage-bot commentedon Dec 19, 2025
This issue is marked P1 but has had no recent status updates.
The P1 label indicates high-priority issues that are at the top of the work list. This is the highest priority level a bug can have if it isn't affecting a top-tier customer or breaking the build. Bugs marked P1 are generally actively being worked on unless the assignee is dealing with a P0 bug (or another P1 bug). Issues at this level should be resolved in a matter of months and should have monthly updates on GitHub.
Please consider where this bug really falls in our current priorities, and label it or assign it accordingly. This allows people to have a clearer picture of what work is actually planned. Thanks!
justinmc commentedon May 4, 2026
This is blocked on dart-lang/sdk#62849.
MarlonJD commentedon May 16, 2026
Migration tooling audit prototype
I started looking into the migration tooling question here and put together a
small dependency-free audit prototype:
https://github.com/MarlonJD/flutter-material-cupertino-migration-audit
This is not meant to be a final implementation. The goal is to make the
practical migration cases concrete before deciding how much should live in
dart fixversus a separate migration tool.What the prototype reports
pubspec.yamldependency additions formaterial_uiandcupertino_ui.imports.
package:flutter/widgets.dart.partfiles.
Early findings
Straightforward cases
Simple unprefixed imports seem mechanically rewritable:
to:
The harder part
Many files use
material.dartorcupertino.dartas umbrella imports for coreframework symbols such as:
Since the new packages are not expected to re-export the full widgets library,
the migration often needs to add explicit framework imports.
Edge cases that probably need special handling
showcombinatorsThese need symbol-level splitting:
could become something like:
hidecombinatorsThese seem risky to rewrite automatically because the hidden symbol set might
change meaning across the split packages.
Public re-exports
These should probably be manual-review cases:
Changing them can affect downstream package APIs, not just the current package.
Prefixed imports
Prefixed design imports are mechanically easy to URI-rewrite:
However, they do not solve unprefixed framework symbol usage elsewhere in the
same file.
partfilesThe design import can live in the library file while the framework symbol usage
appears in a
partfile, so a migration pass needs to consider the wholelibrary unit rather than only one file at a time.
Question for maintainers
Does this audit direction seem useful for this issue?
If so, I can turn it into a targeted Flutter tool/framework PR after guidance on:
dart fix, Flutter tool command, or separate migrationhelper;
bwilkerson commentedon May 17, 2026
Thanks for helping us think this through so we can get this right!
From a UX design perspective, it's important for every tool to be well defined. That is, every tool should have one thing it does, and there shouldn't be multiple tools that do the same thing. The
dart fixtool is focused on fixing problems (diagnostics) in Dart code, which would include most of the items you listed. There is, of course, more to migrating a Flutter app than just fixing diagnostics, and the other pieces should be done by one or more different tools, so the question is still a good one.@kallentu has been thinking about a possible migration tool, though it's scope might be too narrow at this point to handle some of these cases. (Intentionally narrow in order to make the task more manageable, not because we haven't thought about some of these other aspects.)
Updating the
pubspec.yamlfile when a fix required referencing a previously unreferenced package is already part of whatdart fixis capable of doing. And I believe that with the changes @keertip has made to the data-driven fix support, that should already be covered.That's also a pre-existing feature in
dart fix, and we've tested to ensure that it works for this use case as well.That's an interesting case, and I don't think we have that one covered yet. When there's an import of a deprecated library a diagnostic will be generated for it, but I don't think we have any data in the fix data file to capture which libraries should be imported in order to get implicitly imported names.
@keertip We should test this and consider ways to capture this data if we can't already handle the case.
I believe that there's already a diagnostic when one library attempts to export a deprecated library, so assuming that the replaced libraries will be marked as being deprecated the tool will have a signal. This might be a slight variation on the import question above; that is, we might need similar information in order to fix the exports so that the same names are being exported as before.
Good point. I'm not sure whether
dart fixwill currently add combinators when replacing one import (that used combinators) with another. We should test this case.But I do believe that the tool will correctly add a prefix to an import when the name being imported is qualified by an import prefix.
I believe that the fixes already handle references in part files by updating the imports in the root of the library.
The ideal, of course, is for everything that can be automated to be automated. The question is: are there changes that we can't know how to automate? I don't see anything here that clearly makes me think that it should need to manually be done, but I might be missing something.
MarlonJD commentedon May 17, 2026
Thanks, that makes sense. I’ll narrow the prototype/follow-up around validating the existing data-driven fix behavior rather than positioning this as a separate migration tool.
Based on your notes, the main cases worth testing seem to be:
material.dart/cupertino.dartcan causedart fixto add explicit imports such aspackage:flutter/widgets.dart;show/hidecombinators are rewritten or split correctly.I’ll update the prototype/readme to treat pubspec dependency additions, simple URI rewrites, prefixes, and part-file references as expected existing
dart fixcapabilities unless testing shows otherwise.MarlonJD commentedon May 18, 2026
Follow-up: validation PoC for the
dart fixmigration pathI updated the PoC to focus on validating the data-driven
dart fixpath rather than proposing a separate migration tool:https://github.com/MarlonJD/flutter-material-cupertino-migration-audit
The repo now includes:
dart fix, runs the supplement, and compares the result with expected outputValidation command used:
I ran this against a copied Dart SDK to avoid modifying my local Flutter SDK. The validation passed:
The covered cases are:
package:flutter/material.dartandpackage:flutter/cupertino.dartlibrary rewritespackage:flutter/widgets.dartimports for framework symbols previously coming throughmaterial.dart/cupertino.dartshowcombinatorspartfilesmaterial_ui/cupertino_uidependencies topubspec.yamlOne important note: my local Dart SDK is
3.11.5from April 15, 2026, so it may not include the recently landed Dart SDK support from dart-lang/sdk#62849. In that environment,dart fixalone did not apply the full migration; the local supplement completed the remaining cases.Given that dart-lang/sdk#62849 has now landed, would the preferred next step be:
Happy to turn this into a targeted upstream PR once the expected location and scope are clear.
MarlonJD commentedon May 18, 2026
Opened the migration-tooling follow-up in #186658. It is now based on
master, has local validation listed in the PR body, and has no unresolved review threads. Current remaining blockers are review,CICDlabel, and Google testing.Fix data for design packages (flutter#189140)
[CP-beta]Fix data for design packages (#189196)
[CP-beta]Fix data for design packages (#189742)
Piinks commentedon Aug 12, 2026
Closed as done!
github-actions commentedon Aug 26, 2026
This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of
flutter doctor -vand a minimal reproduction of the issue.