rspec/rules/S7109/dart/rule.adoc

Web-only libraries should only be used in Flutter web plugins.

== Why is this an issue?

The following libraries:

* https://dart.dev/libraries/dart-html[`dart:html`]
* https://api.flutter.dev/flutter/dart-js/dart-js-library.html[`dart:js`]
* https://api.flutter.dev/flutter/dart-js_util/dart-js_util-library.html[`dart:js_util`]

are not supported outside of a https://dart.dev/web[web context].

Using them in a non-Flutter library or in a Flutter library that is not a web plugin may lead to runtime errors.

The rule reports an issue on any `import` statement that references one of the above libraries:

[source,dart]
----
import 'dart:html';    // Non compliant
import 'dart:js';      // Non compliant
import 'dart:js_util'; // Non compliant
----

A non-Flutter library is identified as a library with a `pubspec.yaml` file that does not have a dependency on the `flutter` package:

[source,yaml]
----
dependencies:
  other_package: ^1.0.0
  # Missing flutter dependency
----

A Flutter library that is a web plugin is identified as a library with a `pubspec.yaml` file that has a dependency on the `flutter` package and declares the web context, potentially among other platforms:

[source,yaml]
----
name: my_project
dependencies:
  flutter:
    sdk: flutter

flutter:
  plugin:
    platforms:
      web:
        flutter_web: any
        flutter_web_ui: any
      android:
        package: com.example.hello
        pluginClass: HelloPlugin
----

== How to fix it

Remove the dependency to the web-only library.

=== Code examples

==== Noncompliant code example

[source,dart,diff-id=1,diff-type=noncompliant]
----
import 'dart:html';    // Non compliant
import 'dart:js';      // Non compliant
import 'dart:js_util'; // Non compliant
import 'package:other_package/other_library.dart';
----

==== Compliant solution

[source,dart,diff-id=1,diff-type=compliant]
----
import 'package:other_package/other_library.dart';
----

== Resources

=== Documentation

* Dart Docs - https://dart.dev/tools/linter-rules/avoid_web_libraries_in_flutter[Dart Linter rule - avoid_web_libraries_in_flutter]
* Dart API Reference - https://dart.dev/libraries/dart-html[Core libraries - `dart:html`]
* Flutter API Reference - https://api.flutter.dev/flutter/dart-js/dart-js-library.html[Flutter packages - `dart:js`]
* Flutter API Reference https://api.flutter.dev/flutter/dart-js_util/dart-js_util-library.html[Flutter packages - `dart:js_util`]


ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Don't use web-only libraries outside Flutter web plugin packages.

=== Highlighting

The entire `import` statement, including the semi-colon: e.g. `import 'dart:html';`.

endif::env-github,rspecator-view[]