Skip to main content

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.

The library directive is a file-level declaration used to explicitly identify a Dart library and provide a syntactic anchor for library-scoped metadata and documentation. While the Dart compiler implicitly treats every .dart file as a distinct library, the explicit library directive formalizes this boundary and acts as an Abstract Syntax Tree (AST) node for file-level annotations. 
/// Library-level documentation comments precede the directive.
@Deprecated('Use core_network_v2 instead')
library core_network_module;

import 'dart:convert';
import 'dart:io';

part 'network_exceptions.dart';

​
Lexical Placement

If present, the library directive must be the first declaration in a Dart file. It is a structural directive, not executable code, and must appear strictly before any import, export, or part directives. The only elements permitted to precede the library directive are an optional script tag (#!), comments (including /// documentation comments), and its own metadata annotations.

​
Syntax and Naming

Since Dart 2.19, the library directive can be unnamed. This is the recommended syntax when the directive is only needed to attach metadata or documentation, as it avoids inventing a redundant identifier. 
/// Unnamed library directive (Dart 2.19+)
@TestOn('browser')
library;

import 'package:test/test.dart';
If an identifier is provided following the library keyword, it must adhere to specific rules:
  • Standard: The Dart style guide mandates snake_case (lowercase letters separated by underscores) for library names.
  • Dot Notation: Syntactically, Dart allows dot-separated identifiers (e.g., library my_package.core.network;). While considered legacy syntax, it is explicitly permitted by the standard library_names lint rule. However, if the modern unnecessary_library_name lint is enabled, the analyzer will flag all named libraries (including snake_case ones) in favor of the unnamed library; syntax.

​
Implicit vs. Explicit Libraries

The library directive is entirely optional. If omitted, the Dart analyzer and compiler automatically generate an implicit library based on the package name and the file’s URI path. The explicit directive is mechanically required only to provide a target for library-level metadata (@) or Dartdoc documentation (///).

​
Interaction with Part Directives

Historically, a named library directive was required to establish a bidirectional relationship between a parent file and its constituent parts using part and part of. 
// Legacy approach (dependent on library name)
library parent_module;
part 'child_module.dart';

// In child_module.dart:
part of parent_module;
Modern Dart resolves this relationship via URIs rather than library names. The modern compiler prefers part of 'parent_module.dart';, which bypasses the need for a named library identifier entirely.
Master Dart with Deep Grasping Methodology!Learn More