DO use strings in
part of directives
Many Dart developers avoid using
part entirely. They find it easier to reason about their code when each library is a single file. If you do choose to use
part to split part of a library out into another file, Dart requires the other file to in turn indicate which library it’s a part of. For legacy reasons, Dart allows this
part of directive to use the name of the library it’s a part of. That makes it harder for tools to physically find the main library file, and can make it ambiguous which library the part is actually part of.
The preferred, modern syntax is to use a URI string that points directly to the library file, just like you use in other directives. If you have some library,
my_library.dart, that contains:
library my_library; part "some/other/file.dart";
Then the part file should look like:
part of "../../my_library.dart";
part of my_library;
PREFER relative paths when importing libraries within your own package’s
When referencing a library inside your package’s
lib directory from another library in that same package, either a relative URI or an explicit
package: will work.
For example, say your directory structure looks like:
my_package └─ lib ├─ src │ └─ utils.dart └─ api.dart
api.dart wants to import
utils.dart, it should do so using:
There is no profound reason to prefer the former—it’s just shorter, and we want to be consistent.
The “within your own package’s
lib directory” part is important. Libraries inside
lib can import other libraries inside
lib (or in subdirectories of it). Libraries outside of
lib can use relative imports to reach other libraries outside of
lib. For example, you may have a test utility library under
test that other libraries in
But you can’t “cross the streams”. A library outside of
lib should never use a relative import to reach a library under
lib, or vice versa. Doing so will break Dart’s ability to correctly tell if two library URIs refer to the same library. Follow these two rules:
An import path should never contain
A library under
libshould never use
../to escape the
DON’T import libraries that are inside the
src directory of another package.
src directory under
lib is specified to contain libraries private to the package’s own implementation. The way package maintainers version their package takes this convention into account. They are free to make sweeping changes to code under
src without it being a breaking change to the package.
That means that if you import some other package’s private library, a minor, theoretically non-breaking point release of that package could break your code.