diff --git a/src/web/js-interop/js-util.md b/src/web/js-interop/js-util.md new file mode 100644 index 0000000000..ccc902193b --- /dev/null +++ b/src/web/js-interop/js-util.md @@ -0,0 +1,50 @@ +--- +title: The dart:js_util library +short-title: dart:js_util +description: Overview of the utility library for JS interop +--- + +[**`dart:js_util` API docs**][] + +**We will continue to support `dart:js_util` alongside static interop.** + +The `dart:js_util` library, or just `js_util`, is a low-level utility library +for performing JS interop. Because `js_util` is so low-level, +it could potentially be able to provide more flexibility than static interop, +for example, in rare edge cases where `js_interop` is not expressive enough. +This is an exception to the rule; +**please always use static, inline-class based interop by default**. + +The `js_util` library is supported by the JS and `dart2wasm` backends. +It is slower and less ergonomic than `js_interop`. + +The best example of the difference in ergonomics between `js_interop` and +`js_util` is calling equivalent [`external`][] methods. +Each interop solution generates JavaScript code upon calling an `external` method: + +```dart +// js_util external call: +... + +// javascript generated: +... +``` + +The JavaScript code `external` generates for `js_util` is very verbose, +compared to the efficient, compact generation for `js_interop`: + +```dart +// js_interop external call: +... + +// javascript generated: +... +``` + +For optimal JS interop, only use `js_util` over static interop if you encounter +a use case that `js_interop` cannot address +(and please [let us know][] if you encounter such a use case). + +[**`dart:js_util` API docs**]: {{site.dart-api}}/dart-js_util/dart-js_util-library.html +[`external`]: /web/js-interop/reference#external +[let us know]: https://github.com/dart-lang/sdk/issues/new?assignees=&labels=web-js-interop&template=1_issue_template.md&title=Create+an+issue \ No newline at end of file diff --git a/src/web/js-interop/tutorials.md b/src/web/js-interop/tutorials.md new file mode 100644 index 0000000000..74eef4c408 --- /dev/null +++ b/src/web/js-interop/tutorials.md @@ -0,0 +1,29 @@ +--- +title: JS interop tutorials +description: Tutorials for common JavaScript interop use cases in Dart. +--- + +## Tutorials + +### [How to interop with DOM APIs][] + +The browser exposes a number of DOM APIs accessible to Dart through the `dart:js_interop` library. +DOM APIs are the most common set of APIs Dart users will want to expose or interact with while using JS interop. This tutorial shows how to access these APIs and some of the common reasons you may want to use them. + +### [How to interop with JavaScript libraries and apps][] + +Have you found a JS library or app that does exactly what you want to do in your Dart code, but it's way too complex to rewrite in Dart? + +This tutorial will show you how to incorporate methods from an existing JS library. +It will also discuss build and serving options. + +### [How to test and mock JavaScript interop in Dart][] + +Exporting Dart objects with `@JSExport` creates a mock of the object at the JS level, which essentially allows you to test your Dart JS interop code. + +This tutorial will walk through both cases: simply exporting Dart objects to JS, +and then using that same functionality to test JS interop code. + +[How to interop with DOM APIs]: /web/js-interop/dom +[How to interop with JavaScript libraries and apps]: /web/js-interop/js-app +[How to test and mock JavaScript interop in Dart]: /web/js-interop/test-and-mock \ No newline at end of file