Dart Library Prefix

A Dart library prefix is an explicit lexical namespace identifier assigned to an imported library using the as keyword. It encapsulates the imported library’s top-level members (classes, functions, variables, and typedefs) within a designated scope, requiring those members to be accessed via dot notation.

Syntax

import 'URI' as prefix_identifier;

Once prefixed, members of the imported library are accessed using the prefix_identifier.member syntax:

import 'dart:math' as math;

final double result = math.sqrt(math.pi);

Technical Mechanics

• Namespace Binding: By default, Dart imports declarations directly into the library namespace (or library scope) of the importing file. Applying a prefix alters this behavior, binding the library’s export scope strictly to the defined identifier. A prefix is strictly a lexical namespace, not a first-class object. It cannot be assigned to variables, passed as an argument, or manipulated like an object.
• Identifier Resolution: When the Dart compiler encounters prefix.identifier, it restricts the lexical lookup for identifier exclusively to the scope bound to prefix.
• Shared Namespaces: Dart allows multiple libraries to be imported under the same prefix. Doing so merges the exported members of all those libraries into a single, shared lexical namespace.

import 'library_one.dart' as shared_prefix;
import 'library_two.dart' as shared_prefix;

void main() {
  // Members from both libraries are resolved through 'shared_prefix'
  shared_prefix.functionFromOne();
  shared_prefix.functionFromTwo();
}

• Extension Resolution: When a library containing Dart Extensions is imported with a prefix, its extension methods are hidden from implicit resolution and are no longer automatically applied to types. They must be invoked explicitly using the prefix and the extension’s name.

import 'string_extensions.dart' as str_ext;

void main() {
  // Implicit resolution is disabled; this will fail:
  // 'text'.customMethod(); 

  // Explicit invocation is required:
  str_ext.StringExtension('text').customMethod();
}

• Combinator Interaction: Prefixes can be used in conjunction with show and hide combinators. The Dart analyzer applies the combinator filters to the library’s API before binding the remaining members to the prefix namespace.

// Only the 'Random' class is bound to the 'math' prefix.
import 'dart:math' as math show Random;

void main() {
  math.Random rng = math.Random();
}

• Deferred Loading Requirement: A library prefix is syntactically mandatory when implementing deferred (lazy) loading via the deferred as keywords. The prefix provides the lexical namespace required to invoke the asynchronous loadLibrary() method, which the Dart runtime uses to load the library into memory.

import 'package:heavy_module/heavy_module.dart' deferred as heavy;

Future<void> initialize() async {
  // The prefix provides lexical access to the loadLibrary() Future
  await heavy.loadLibrary();
  heavy.executeTask();
}

Tired of Poor Dart Skills? Fix That With Deep Grasping!

Learn More