Skip to main content
The Pragma annotation is a metadata directive used to provide implementation-specific hints to the Dart compiler, runtime, or static analysis tools. It allows developers to influence toolchain behavior—such as compilation strategies or tree-shaking logic—without altering the semantic logic defined by the Dart language specification.

​
Class Definition

The annotation is an instance of the Pragma class, defined in dart:core. 
class Pragma {
  final String name;
  final Object? options;
  
  const Pragma(this.name, [this.options]);
}

​
Syntax

The annotation is applied as a prefix to declarations (classes, fields, methods, or functions) by invoking the const constructor of the Pragma class. It requires a name string and accepts an optional options object. 
// Basic usage with a name only
@Pragma('tool_identifier:directive')
void targetFunction() {
  // ...
}

// Usage with optional configuration data
@Pragma('tool_identifier:directive', {'setting': true})
class TargetClass {
  // ...
}

​
Parameters

  1. name (String): A key string identifying the specific hint. This string must match a directive recognized by the target tool (e.g., the Dart VM, dart2js, or the analyzer). Conventionally, these strings are namespaced (e.g., vm:entry-point, dart2js:noInline).
  2. options (Object?): An optional payload providing additional context or configuration for the directive. The expected type and structure of this object depend entirely on the specific name provided and the tool consuming it.

​
Resolution Mechanics

  • Tool-Specific: The behavior triggered by a Pragma is defined entirely by the implementation of the compiler or runtime processing the code.
  • Ignored by Default: If a tool encounters a Pragma with a name it does not recognize, the annotation is ignored silently. It does not produce compilation errors or runtime exceptions.
  • Multi-Targeting: Because unrecognized pragmas are ignored, a single declaration may carry multiple Pragma annotations targeting different tools (e.g., one for the VM and one for the web compiler) without conflict.
Master Dart with Deep Grasping Methodology!Learn More