Skip to content

Commit

Permalink
New JS interop docs (#4578)
Browse files Browse the repository at this point in the history
Fixes #5438 
---------

Co-authored-by: Srujan Gaddam <[email protected]>
Co-authored-by: Parker Lougheed <[email protected]>
Co-authored-by: sigmundch <[email protected]>
  • Loading branch information
4 people authored Feb 15, 2024
1 parent 6c5d2d7 commit 4a2fd1b
Show file tree
Hide file tree
Showing 16 changed files with 1,361 additions and 135 deletions.
2 changes: 1 addition & 1 deletion examples/create_libraries/lib/hw_mp.dart
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,4 @@ library hw_mp;
// #docregion export
export 'src/hw_none.dart' // Stub implementation
if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
if (dart.library.html) 'src/hw_html.dart'; // dart:html implementation
if (dart.library.js_interop) 'src/hw_web.dart'; // package:web implementation
4 changes: 2 additions & 2 deletions firebase.json
Original file line number Diff line number Diff line change
Expand Up @@ -172,11 +172,11 @@
{ "source": "/go/non-promo-this", "destination": "/tools/non-promotion-reasons#this", "type": 301 },
{ "source": "/go/non-promo-write", "destination": "/tools/non-promotion-reasons#write", "type": 301 },

{ "source": "/go/next-gen-js-interop", "destination": "/interop/js-interop#next-generation-js-interop-preview", "type": 301 },
{ "source": "/go/next-gen-js-interop", "destination": "/interop/js-interop", "type": 301 },
{ "source": "/go/null-safety-migration", "destination": "/null-safety/migration-guide", "type": 301 },
{ "source": "/go/package-discontinue", "destination": "/tools/pub/publishing#discontinue", "type": 301 },
{ "source": "/go/package-retraction", "destination": "/tools/pub/publishing#retract", "type": 301 },
{ "source": "/go/package-web", "destination": "https://pub.dev/packages/web", "type": 301 },
{ "source": "/go/package-web", "destination": "/interop/js-interop/package-web", "type": 301 },
{ "source": "/go/pub-cache", "destination": "/tools/pub/cmd/pub-cache", "type": 301 },
{ "source": "/go/pubignore", "destination": "/tools/pub/publishing#what-files-are-published", "type": 301 },
{ "source": "/go/publishing-from-github", "destination": "/tools/pub/automated-publishing#publishing-packages-using-github-actions", "type": 301 },
Expand Down
16 changes: 15 additions & 1 deletion src/_data/side-nav.yml
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,21 @@
- title: Java & Kotlin interop
permalink: /interop/java-interop
- title: JavaScript interop
permalink: /interop/js-interop
children:
- title: Overview
permalink: /interop/js-interop
match-page-url-exactly: true
- title: Usage
permalink: /interop/js-interop/usage
- title: JS types
permalink: /interop/js-interop/js-types
- title: Tutorials
permalink: /interop/js-interop/tutorials
- title: Past JS interop
permalink: /interop/js-interop/past-js-interop
- divider
- title: Web interop
permalink: /interop/js-interop/package-web

- title: Tools & techniques
expanded: false
Expand Down
10 changes: 5 additions & 5 deletions src/content/guides/libraries/create-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ by importing a single file.

The lib directory might also include other importable, non-src, libraries.
For example, perhaps your main library works across platforms, but
you create separate libraries that rely on `dart:io` or `dart:html`.
you create separate libraries that rely on `dart:io` or `dart:js_interop`.
Some packages have separate libraries that are meant to be imported
with a prefix, when the main library is not.

Expand Down Expand Up @@ -151,23 +151,23 @@ A common use case is a library that supports both web and native platforms.
To conditionally import or export,
you need to check for the presence of `dart:*` libraries.
Here's an example of conditional export code that
checks for the presence of `dart:io` and `dart:html`:
checks for the presence of `dart:io` and `dart:js_interop`:

<?code-excerpt "create_libraries/lib/hw_mp.dart (export)"?>
```dart title="lib/hw_mp.dart"
export 'src/hw_none.dart' // Stub implementation
if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
if (dart.library.html) 'src/hw_html.dart'; // dart:html implementation
if (dart.library.js_interop) 'src/hw_web.dart'; // package:web implementation
```

Here's what that code does:

* In an app that can use `dart:io`
(for example, a command-line app),
export `src/hw_io.dart`.
* In an app that can use `dart:html`
* In an app that can use `dart:js_interop`
(a web app),
export `src/hw_html.dart`.
export `src/hw_web.dart`.
* Otherwise, export `src/hw_none.dart`.

To conditionally import a file, use the same code as above,
Expand Down
2 changes: 1 addition & 1 deletion src/content/guides/whats-new.md
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,7 @@ we made the following changes:
[source descriptor]: /tools/pub/cmd/pub-add#source-descriptor
[SDK archive]: /get-dart/archive
[glossary]: /resources/glossary
[JS static interop support]: /interop/js-interop#next-generation-js-interop-preview
[JS static interop support]: /interop/js-interop
[analyzer plugins]: /tools/analysis#plugins

### Articles added to the Dart blog {:.no_toc}
Expand Down
123 changes: 0 additions & 123 deletions src/content/interop/js-interop.md

This file was deleted.

44 changes: 44 additions & 0 deletions src/content/interop/js-interop/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: JavaScript interoperability
short-title: JS interop
description: Integrate JavaScript code into your Dart web app.
---

The [Dart web platform](/overview#web-platform) supports communication with
JavaScript apps and libraries, as well as browser APIs, using `dart:js_interop`.

Web developers can benefit from using external JS libraries in their Dart code,
without having to rewrite anything in Dart.

{% comment %}
## Why use JS interop?

TODO: Should we have a paragraph here explaining the benefits of using interop?
{% endcomment %}

## Overview

For information on how to write and use JavaScript interop:
* [Usage reference]
* [JS types reference]

For information on interacting with web APIs:
* [`package:web` and migration]

For tutorials and help:
* [How to mock JavaScript interop objects]

For information on previous JavaScript interop libraries:
* [Past JS interop]

For additional documentation on JavaScript interop:
* [`dart:js_interop` API reference]
* [`dart:js_interop_unsafe` API reference]

[Usage reference]: /interop/js-interop/usage
[JS types reference]: /interop/js-interop/js-types
[`package:web` and migration]: /interop/js-interop/package-web
[How to mock JavaScript interop objects]: /interop/js-interop/mock
[Past JS interop]: /interop/js-interop/past-js-interop
[`dart:js_interop` API reference]: https://api.dart.dev/dev/dart-js_interop/dart-js_interop-library.html
[`dart:js_interop_unsafe` API reference]: https://api.dart.dev/dev/dart-js_interop_unsafe/dart-js_interop_unsafe-library.html
Loading

0 comments on commit 4a2fd1b

Please sign in to comment.