Skip to content

Investigate dart fix or other options for material/cupertino migration #172935

Closed

Description

@Piinks

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.

Activity

  1. added
    P1High-priority issues at the top of the work list
    team-designOwned by Design Languages team
    triaged-designTriaged by Design Languages team
    on Jul 30, 2025
  2. a-siva commented on Jul 30, 2025

    @a-siva
    Contributor

    //cc @srawlins @pq is this something that is feasible in dart fix

  3. Piinks commented on Jul 30, 2025

    @Piinks
    ContributorAuthor

    Thank @a-siva! Also touched base with @bwilkerson. I am putting together a doc of potential things to look at together. :)

  4. srawlins commented on Jul 30, 2025

    @srawlins
    Contributor

    Yeah this sounds like it might be a data-driven migration, if it's possible. Best contacts are @bwilkerson and @keertip

  5. bwilkerson commented on Aug 12, 2025

    @bwilkerson
    Contributor

    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.

  6. bwilkerson commented on Aug 14, 2025

    @bwilkerson
    Contributor

    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.

  7. flutter-triage-bot commented on Dec 19, 2025

    @flutter-triage-bot

    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!

  8. justinmc commented on May 4, 2026

    @justinmc
    Contributor

    This is blocked on dart-lang/sdk#62849.

  9. MarlonJD commented on May 16, 2026

    @MarlonJD
    Contributor

    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 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.

    Early findings

    Straightforward cases

    Simple unprefixed imports seem mechanically rewritable:

    import 'package:flutter/material.dart';
    import 'package:flutter/cupertino.dart';

    to:

    import 'package:material_ui/material_ui.dart';
    import 'package:cupertino_ui/cupertino_ui.dart';

    The harder part

    Many files use material.dart or cupertino.dart as umbrella imports for core
    framework symbols such as:

    Widget, BuildContext, StatelessWidget, StatefulWidget, State, Text, Navigator,
    EdgeInsets, Color, VoidCallback, AnimationController, TextInputFormatter
    

    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

    show combinators

    These need symbol-level splitting:

    import 'package:flutter/material.dart' show BuildContext, Scaffold, Widget;

    could become something like:

    import 'package:material_ui/material_ui.dart' show Scaffold;
    import 'package:flutter/widgets.dart' show BuildContext, Widget;

    hide combinators

    These 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:

    export 'package:flutter/material.dart';
    export 'package:flutter/cupertino.dart';

    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.
  10. bwilkerson commented on May 17, 2026

    @bwilkerson
    Contributor

    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.

  11. MarlonJD commented on May 17, 2026

    @MarlonJD
    Contributor

    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.

  12. MarlonJD commented on May 18, 2026

    @MarlonJD
    Contributor

    Follow-up: validation PoC for the dart fix migration path

    I updated the PoC to focus on validating the data-driven dart fix path rather than proposing a separate migration tool:

    https://github.com/MarlonJD/flutter-material-cupertino-migration-audit

    The repo now includes:

    • 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:

    1. 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
    2. 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.

  13. MarlonJD commented on May 18, 2026

    @MarlonJD
    Contributor

    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.

  14. added a commit that references this issue on Jul 9, 2026
  15. Piinks commented on Aug 12, 2026

    @Piinks
    ContributorAuthor

    Closed as done!

  16. github-actions commented on Aug 26, 2026

    @github-actions

    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.

  17. locked as resolved and limited conversation to collaborators on Aug 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1High-priority issues at the top of the work listdependency: dartDart team may need to help usdependency:dart-triagedTriaged by Dart teamteam-designOwned by Design Languages teamtriaged-designTriaged by Design Languages team

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions