Skip to content

[Decoupling] Migrate cross-library docImports #181288

Open

Description

@justinmc

Dart docImports allow you to reference identifiers from outside of the current file using square brackets in Dart Doc. The framework contains many of these that reference Material or Cupertino and will need to be migrated before decoupling can be completed.

What should we do about problematic docImports?

docImports are problematic when they reference Material or Cupertino from outside of that referenced library. For example, widgets/scrollbar.dart references both Material and Cupertino so that it can refer to things like [Scrollbar] and [CupertinoScrollbar] in its docs.

/// @docImport 'package:flutter/cupertino.dart';
/// @docImport 'package:flutter/material.dart';

Option 0: Do nothing

This is not viable in the long term because it will break dart doc after Material and Cupertino are removed from flutter/flutter. The references in the example above to material.dart and cupertino.dart will not be found.

In the short term immediately after decoupling, because we plan to keep the original Material and Cupertino code in flutter/flutter during a deprecation period, it will not break anything. However, users that click on these links in the framework docs will be taken to the deprecated versions of this code, which is misleading.

Option 1: Remove affected docImports

We could remove the problematic docImports and replace the linked identifiers with unlinked inline code. In the scrollbar.dart example above, we would remove the two docImports and replace [Scrollbar] with `Scrollbar`.

This is an imperfect solution because users of our docs would lose a lot of useful links.

Options 2: Migrate each problematic docImport to reference the new external package

We would have to add a dev dependency on material_ui and cupertino_ui, and it's unclear if this would cause any problems.

Where are problematic docImports located?

Problematic docImports have been seen in the following places, but they may also exist elsewhere:

  • packages/flutter_test
  • packages/flutter/test
  • packages/flutter/lib/src/widgets
  • packages/flutter/lib/src/material
  • packages/flutter/lib/src/cupertino

How can we prevent this problem in the future?

We should ideally include a lint that can catch problematic docImports, similar to what was done for cross-library test imports in #178693.

Links

This was discovered by @navaronbracke in: https://github.com/flutter/flutter/pull/180456/files#r2700767565

Activity

  1. added
    in triagePresently being triaged by the triage team
    a: tests"flutter test", flutter_test, or one of our tests
    frameworkflutter/packages/flutter repository. See also f: labels.
    p: material_uimaterial_ui package in flutter/packages
    p: cupertino_uicupertino_ui package in flutter/packages
    c: proposalA detailed proposal for a change to Flutter
    and removed
    in triagePresently being triaged by the triage team
    on Jan 22, 2026
  2. added
    P1High-priority issues at the top of the work list
    on Jan 27, 2026
  3. dkwingsmt commented on Jan 30, 2026

    @dkwingsmt
    Contributor

    Are you sure they're not supported? I see some docImport of other packages. For example, https://api.flutter.dev/flutter/flutter_test/testWidgets.html references Future from dart:async and LeakTesting.settings from package:leak_tracker_testing. It seems that the the entire doc for the related packages are generated and included (instead of referencing their own doc website (understandably)), which works despite not seeming optimally space efficient.

  4. navaronbracke commented on Jan 30, 2026

    @navaronbracke
    Contributor

    dart:async is a core library, though. (which should always work) And testWidgets works, because of the dependency: https://github.com/flutter/flutter/blob/main/packages/flutter_test/pubspec.yaml#L39

  5. dkwingsmt commented on Jan 31, 2026

    @dkwingsmt
    Contributor

    I'm sure it needs to involve some kind of dependency. Would it work if we add material and cupertino as dev_dependencies?

  6. flutter-triage-bot commented on Jun 6, 2026

    @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!

  7. added
    packageflutter/packages repository. See also p: labels.
    and removed
    frameworkflutter/packages/flutter repository. See also f: labels.
    on Aug 17, 2026
  8. added
    team-designOwned by Design Languages team
    triaged-designTriaged by Design Languages team
    and removed on Aug 26, 2026
  9. changed the title [-]Migrate cross-library docImports before decoupling[/-] [+][Decoupling] Migrate cross-library docImports[/+] on Sep 24, 2026
  10. justinmc commented on Sep 24, 2026

    @justinmc
    ContributorAuthor

    It seems we should add dev dependencies on material_ui and cupertino_ui to packages/flutter/pubspec.yaml. We should watch out for possible side effects though: 1. Will changes to widgets etc. that break material_ui or cupertino_ui cause a CI failure now? Maybe that's ok, we shouldn't break them anyway. 2. Will this cause any problems in google3?

  11. dkwingsmt commented on Sep 24, 2026

    @dkwingsmt
    Contributor

    Looking at it now I think the framework should migrate away from these references, because the libraries are just customers to these basic widgets, which shouldn't appoint them as the major purpose. Maybe in appropriate cases you can reference them in "See also" as "excellent examples", in which case you can reference by URLs.

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 lista: tests"flutter test", flutter_test, or one of our testsc: proposalA detailed proposal for a change to Flutterp: cupertino_uicupertino_ui package in flutter/packagesp: material_uimaterial_ui package in flutter/packagespackageflutter/packages repository. See also p: labels.team-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