Skip to content

Commit

Permalink
new pages left out of last commit
Browse files Browse the repository at this point in the history
  • Loading branch information
MaryaBelanger committed Feb 7, 2023
1 parent 9895fb6 commit 6e989f3
Show file tree
Hide file tree
Showing 2 changed files with 79 additions and 0 deletions.
50 changes: 50 additions & 0 deletions src/web/js-interop/js-util.md
Original file line number Diff line number Diff line change
@@ -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
29 changes: 29 additions & 0 deletions src/web/js-interop/tutorials.md
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 6e989f3

Please sign in to comment.