Conditional Imports in Flutter: One API, Every Platform
Use dart.library.io and dart.library.js_interop conditions to split a single storage API into native and web implementations at compile time.
Published on • November 5, 2026
AI Assistant

dart:io does not compile on the web, and dart:js_interop does not compile on the VM — yet your app code should not care. Conditional imports let you publish one API and let the compiler pick the right implementation file for each target, which is exactly how storage, file, and networking services stay portable.
The stub / impl / impl pattern
Dart’s create packages guide documents the canonical shape. You keep three files plus a single public entry point:
// lib/storage_service.dart (public entry point)
export 'src/storage_stub.dart' // fallback: throws
if (dart.library.io) 'src/storage_io.dart' // VM / mobile / desktop
if (dart.library.js_interop) 'src/storage_web.dart'; // web (package:web)
Consumers write one import — import 'package:my_app/storage_service.dart'; — and never think about platforms again. All conditionally exported libraries must implement the same API; the stub throws UnsupportedError so an unsupported platform fails loudly instead of silently:
// lib/src/storage_stub.dart
void write(String key, String value) =>
throw UnsupportedError('storage_stub write');
String? read(String key) => throw UnsupportedError('storage_stub read');
How the conditions actually work
The guide is explicit: conditional imports “only work with keys in the compilation environment,” and today only keys of the form dart.library.name exist. A key evaluates to "true" when the library dart:name is available for use on the current platform — not whether you imported it.
The order of the clauses matters — the first matching condition wins, and the unconditioned file is the final fallback. Crucially, the platform that does not match has its file excluded from compilation entirely, so a web build never tries to link dart:io.
dart.library.html is out; dart.library.js_interop is in
The old idiom checked dart.library.html, but the package:web migration guide now recommends dart.library.js_interop instead:
export 'src/hw_none.dart' // Stub implementation
if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
if (dart.library.js_interop) 'src/hw_web.dart'; // package:web implementation
The reason: dart:html and friends are deprecated, are not supported when compiling to Wasm, and are being replaced long-term by package:web, which is built on dart:js_interop. Checking dart.library.js_interop keeps the same branch working for both JavaScript and WebAssembly web builds.
A complete storage service
// lib/src/storage_io.dart
import 'dart:convert';
import 'dart:io';
class AppStorage {
AppStorage(this._file);
final File _file;
Map<String, dynamic> _load() {
if (!_file.existsSync()) return {};
return jsonDecode(_file.readAsStringSync()) as Map<String, dynamic>;
}
void write(String key, Object value) {
final data = _load()..[key] = value;
_file.writeAsStringSync(jsonEncode(data));
}
String? read(String key) => _load()[key] as String?;
}
// lib/src/storage_web.dart
import 'dart:convert';
import 'package:web/web.dart';
class AppStorage {
void write(String key, Object value) {
window.localStorage.setItem(key, jsonEncode(value));
}
String? read(String key) => window.localStorage.getItem(key);
}
Both classes expose write and read, so the conditional export in storage_service.dart type-checks identically on every target. Apps built on mobile or desktop get the file-backed version; the web build gets localStorage.
Conditional imports vs deferred as lazy loading
These are different mechanisms solving different problems, as the Dart libraries guide explains:
- Conditional imports choose which file compiles into your program, based on platform availability. The selection happens at compile time; only one implementation ends up in the build.
deferred as+loadLibrary()defers when code is loaded at runtime:import 'package:greetings/hello.dart' deferred as hello;thenawait hello.loadLibrary();. Its goal is reducing initial startup time or splitting rarely used screens — thedarttool only supports it for web targets, and Flutter maps it to deferred components on Android.
You can even combine both: conditionally pick the platform file, and defer the heavy one. Just remember the deferred-loading restrictions — you can’t use types from a deferred library in the importing file until it’s loaded, and its constants aren’t constant in the importer.
Takeaway: Give every platform-specific feature one public entry point, use if (dart.library.io) and if (dart.library.js_interop) to route to io/web implementations (avoid dart.library.html), and reserve deferred as for runtime lazy loading rather than platform selection.