> ## 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.
# Dart Library Directive
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.
```dart theme={"dark"}
/// 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.
```dart theme={"dark"}
/// 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`.
```dart theme={"dark"}
// 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.
Tired of Poor Dart Skills? Fix That With Deep Grasping!
Learn More
