[lint][proposal] Add lint to enforce package imports to avoid duplicate library loading

[MasahideMori-SimpleAppli]

Proposal: Add lint to enforce package imports and avoid duplicate library loading

Summary

When mixing relative and package: imports for the same Dart file, Dart treats them as separate libraries.
This can lead to multiple instances of singletons or static state, breaking expected behavior in Flutter and Dart projects.
We propose a new lint rule to detect and warn about relative imports in lib/ directories, enforcing package imports to prevent this issue.

---

Problem / Usage Example

Investigation revealed the root cause:

• Related Flutter issue: [Web]The singleton pattern breaks. flutter/flutter#171324

The problem occurs because the singleton class is imported differently depending on the worker's environment
(this can be influenced by IDE auto-import behavior and other factors):

• Screen A:

import 'package:app_name/abc/app_manager.dart';

• Screen B:

import '../../../abc/app_manager.dart';

These imports currently create separate instances, breaking the singleton pattern.

This behavior is due to Dart's URI resolution:

• SDK issue: Two internal types created from one type declaration when a test uses relative imports #41868
• Language issue: Dart uses raw URIs for library identity. language#939

According to the Dart specification:

• Section 19.5:

  Note that a relative URI is interpreted relative to the location of the enclosing library (Section 19.7), which means that L1 and L2 may both have a part identified by 'myPart.dart', but they are not the same URI unless L1 and L2 have the same location.

• Section 19.7:

  A URI of the form package:s is interpreted in an implementation-specific manner.
  Otherwise, any relative URI is interpreted relative to the location of the current library. All further interpretation of URIs is implementation-dependent.

In practice, this means that the same Dart file can be loaded twice under different URIs, causing multiple instances of singletons.

---

Proposed Solution

Introduce a new lint rule (e.g., always_use_package_imports) that:

• Issues a warning when a relative import is used in a lib/ directory
• Encourages the use of package: imports for all files within lib/
• Helps prevent duplicate library instances and ensures singletons behave correctly

Example Configuration for projects

pubspec.yaml

dev_dependencies:
  lints: ^6.0.0

analysis_options.yaml

include: package:lints/recommended.yaml

linter:
  rules:
    # Enforce package imports
    always_use_package_imports: true
    prefer_relative_imports: false

analyzer:
  exclude:
    - build/**
    - test/**

Additional Considerations

• IDEs like Android Studio may generate relative or package imports differently depending on the user environment.
• Configuring the IDE to default to package imports would reduce the likelihood of this problem.
• This lint would not be a breaking change; existing relative imports would simply trigger a warning.

---

References

• Flutter issue #171324
• Dart SDK issue #41868
• Dart language issue #939
• Dart Language Specification

[FMorschel]

This is a project preference I don't believe the team will agree on doing. You can create your own package like https://pub.dev/packages/very_good_analysis and always use that set of rules if this is something you are concerned about.

Already activating always_use_package_imports and setting prefer_relative_imports to false should handle that, and our tooling (quick-fixes, auto-complete) should do the correct job of considering the active rules. If you find any problems with that, please file issues here so we can fix them.

About importing the same file twice, you can give names to your libraries and that should avoid your issue too (see #61529 (comment)).

CC @bwilkerson @lrhn

[bwilkerson]

I'm not sure I understand the original request. There is already a lint named always_use_package_imports that should do what I think you're asking for.

There's no reason to explicitly disable prefer_relative_imports because it doesn't appear to be enabled by the recommended lint set.

As far as I can tell, what you're asking for already exists. If I've misunderstood, please let me know and we can re-open this issue.

[MasahideMori-SimpleAppli]

@FMorschel , @bwilkerson
Thank you very much for reviewing and clarifying this issue.

I understand your point — the lint itself already exists, and it makes sense that enabling it by default may not be suitable for every project.
For now, I’ll think about creating a custom lint package with stricter import rules for our own projects.

Thanks!