Dart Conditional Import

Conditional imports in Dart allow the compiler to dynamically select which library URI to load at compile-time based on the target platform’s available libraries or environment declarations. This mechanism ensures that platform-specific code is only parsed, compiled, and bundled when the specified condition evaluates to true.

Syntax

The syntax utilizes the import statement followed by one or more if clauses.

import 'default_stub.dart'
    if (dart.library.io) 'native_implementation.dart'
    if (dart.library.html) 'web_implementation.dart'
    if (custom_env_var == 'true') 'custom_implementation.dart';

The compiler evaluates the conditions sequentially. The first condition that evaluates to true dictates which file is imported. If no conditions are met, the compiler falls back to the initial URI (default_stub.dart).

Conditional Exports

The exact same conditional logic can be applied to the export directive.

export 'default_stub.dart'
    if (dart.library.io) 'native_implementation.dart'
    if (dart.library.html) 'web_implementation.dart';

Evaluation Conditions

Conditions are based on compile-time environment declarations, which are evaluated as strings. Core Library Checks The syntax dart.library.<name> checks a built-in environment declaration. It evaluates to true because the compiler sets that specific environment variable to the string "true" when the corresponding core library is available on the current compilation target. It does not return a boolean type.

dart.library.io: Evaluates to true on the Dart VM (Native platforms like Windows, macOS, Linux, iOS, Android).
dart.library.html: Evaluates to true when compiling for the Web.
dart.library.js_interop: Evaluates to true when compiling for the Web (modern alternative to html).

Environment Declarations Conditions can evaluate custom compile-time environment variables passed to the Dart compiler (e.g., via the --dart-define flag).

Equality check: if (my_custom_var == 'true') or if (my_custom_var == 'expected_value')
Shorthand check: if (my_custom_var). In Dart, this is strictly a shorthand for if (my_custom_var == 'true'). It does not check if the variable merely exists. If the environment variable is defined as 'false', the condition evaluates to false.

Static Analysis and API Resolution

Because Dart is statically typed, the analyzer and compiler must resolve types and method signatures for the active compilation target.

Context-Aware Analysis: The Dart analyzer evaluates the if conditions based on the active analysis context (e.g., analyzing for Web vs. VM). It provides static analysis, type checking, and autocomplete features based on the resolved file for that specific context, not strictly the default fallback file.
Member Resolution: The Dart compiler does not enforce a strict rule that all conditionally imported files must expose the exact same public API surface. It only requires that the specific members (classes, functions, variables) actually invoked by the importing file exist in the file that is resolved for the current compilation target.

While maintaining an identical API across the default stub and all conditional targets is a standard developer best practice to prevent compilation errors across different targets, it is not a language-enforced rule. Example of a Default Stub (default_stub.dart):

class PlatformHandler {
  void execute() => throw UnsupportedError('Unsupported platform');
}

Example of a Conditional Target (native_implementation.dart):

import 'dart:io';

class PlatformHandler {
  // This member is invoked by the importing file, so it must exist here.
  void execute() {
    print('Running on ${Platform.operatingSystem}');
  }
  
  // The compiler permits additional members not present in the stub, 
  // provided the importing file does not attempt to call them when 
  // this file is not the resolved target.
  void nativeSpecificMethod() {} 
}