Libraries

DO

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";

And not:

part of my_library;

PREFER

PREFER relative paths when importing libraries within your own package’s lib directory.

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

If api.dart wants to import utils.dart, it should do so using:

import 'src/utils.dart';

And not:

import 'package:my_package/src/utils.dart';

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

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 /lib/.
• A library under lib should never use ../ to escape the lib directory.

DON'T

DON’T import libraries that are inside the src directory of another package.

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