Library Prefix

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Syntax

import 'URI' as prefix_identifier;

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();
}