# History of JS interop in Dart

> Support for Wasm just landed in the current Flutter beta, thanks to an exciting JavaScript interop milestone reached in Dart 3.3. To…




### Support for Wasm just landed in the current Flutter beta, thanks to an exciting JavaScript interop milestone reached in Dart 3.3. To celebrate, we’re taking a look back at the decade-long journey of Dart and JS interoperability.

<DashImage src="images/1dhBQqKXU46sGKjx36LNf0w.webp" alt="Dash, the Dart and Flutter mascot, walking through an open door labeled with JavaScript interop-related terms." caption="AI Image generated by Gemini" />


Interoperability has been a core focus from the beginning of Dart. When Dart was first released in 2011, it was designed to be *embeddable* and *multi-platform*. It ran on a standalone virtual machine, embedded in a browser, and compiled to JavaScript. When Flutter came along in 2015, we were ready to embed it there, too. Now, we’re excited to [target WasmGC runtimes](https://docs.flutter.dev/platform-integration/web/wasm), as well.

At first, we worked quickly to expose the capabilities of each platform where Dart was embedded. That’s how our SDK platform-specific libraries emerged: [`dart:io`](https://api.dart.dev/stable/dart-io/dart-io-library.html) exposed the file system on the VM, [`dart:html`](https://api.dart.dev/stable/dart-html/dart-html-library.html) exposed the browser APIs on the web, and so on. These libraries looked and felt like regular Dart libraries, but behind the scenes hid some sophisticated low-level, native primitives to make them work. This was the very first form of interop we ever invented. It was expressive, but restricted to only SDK libraries.

On the web, developers needed access to more than just browser APIs. So we started looking at ways to open interoperability to cover more targets. As a starting point, we introduced [`dart:js`](https://codereview.chromium.org//15782009) in 2013 to enable access to JavaScript libraries.

```javascript
// Short example JavaScript code to illustrate Dart/JS interop
window.myTopLevel = {
  field1: 0,
  method2() {
    return this.field1;
  }
}

// Access via `dart:js` (2013)
import 'dart:js' as js;

void main() {
  // This line has a typo! oops :(
  var object = js.context['myTopLevl'];
  object['field1'] = 1;
  // This call fails with a noSuchMethod because method2
  // returns an int, oops
  object.callMethod('method2', []).substr(1);
}
```


We knew then that `dart:js` was not the programming model we wanted. You had to use strings to access names from JavaScript — forget about finding issues at compile-time, and don’t even think about code completion! The implementation was expensive, too. It heavily relied on boxes and deep copies for most operations. So we continued [drafting](https://github.com/dart-archive/js-interop-deprecated) ideas in 2014 and 2015 until v0.6 of `package:js` was released.

```dart
// Access via `package:js` (2015)
import 'package:js/js.dart';

// Magic annotations allow us to declare API signatures:
@JS()
class MyObject {
  external int get field1;
  external void set field1(int value);
  external String method2();
}

@JS()
external MyObject get myTopLevel;

void main() {
  // Access to code is less error prone: analyzer can check that
  // these symbols match a declaration, and we get code-completion too!
  var object = myTopLevel;
  object.field1 = 1;
  // But types are not checked, this unsoundly invokes substring on an int
  object.method2().substring(1);
}
```


With [`package:js`](https://pub.dev/documentation/js/latest/) we finally had an open API that was efficient and user friendly. You could sprinkle some annotations on abstract classes, and *voila,* you had access to JavaScript APIs. It all worked like magic, until it didn’t. There was a lot you couldn’t do with `package:js`: accessing browser APIs directly, renaming members, conversions, attaching Dart logic, and [more](https://github.com/dart-lang/sdk/issues/35084). To compensate, we also shipped [`dart:js_util`](https://codereview.chromium.org/2150313003/) — a lightweight and efficient low-level API similar to `dart:js`, as a fallback. All the limitations in `package:js` really bothered us, but our hands were tied. We needed more from the Dart language to do better.

Around that time, we were already working on the biggest change to the language we have ever made — we were making Dart [sound](https://dart.dev/language/type-system#what-is-soundness). Ironically, when we released the new type system with Dart 2.0 in 2018, interoperability got *worse*! Beyond those early limitations, that magic that made `package:js` special had a dark side — it couldn’t check the validity of types. This meant that our interoperability was a source of unsoundness in our otherwise sound language.

Then, our journey changed to focus on improving both Dart and JS-interop as a concerted effort. With clear principles (be idiomatic, expressive, compositional, precise, approachable, pragmatic, non-magical, and complete) we steered towards a design that anchored on typing and static dispatching, and that challenged the Dart language. What followed was a side-by-side evolution.

* In 2019, Dart 2.7 added static extension methods. You could attach custom Dart logic to a JS-interop class and convert values, like a JS `Promise` into a Dart `Future`, without using wrappers.

* In 2021, we released `@staticInterop` with `package:js` v0.6.4. At last, JS-interop was expressive enough — you could expose browser APIs that previously were exclusively managed by SDK libraries like `dart:html`.

* In 2023, when we dropped unsound null safety in Dart 3.0, we could finally see the progress we had made, our designs and `@staticInterop` work made it clear we were ready to address the soundness gap we had for so long.

That year, we introduced compilation to WasmGC and leveraged JS-interop to run rich frameworks like [Flutter web](https://flutter.dev/blog/whats-next-for-flutter) on it. This sparked work on [JS Types](https://dart.dev/interop/js-interop/js-types) to clearly define the Dart and JS boundary in the programming model and find a consistent way to work with JS in both Wasm and JS compilation targets. We also started the [extension types](https://dart.dev/language/extension-types) language experiment — a feature launched in Dart 3.3 that bridges the gap between the Dart language and JS-interop. For years, JS-interop had behaviors, like type erasure, that didn’t match anything else in Dart. With extension types, JS-interop could finally be idiomatic and get the support it deserves in Dart development tools.

Despite the many shifts and turns along the way, one thing remained consistent throughout the entire decade: the active engagement of our Dart community. Community members took early steps testing and contributing to `dart:js`, then later influencing the design of `package:js`. They wrote tools to address feature gaps ([`package:js_wrapping`](https://github.com/a14n/dart-js-wrapping)), and experimented with ways to improve productivity by autogenerating Dart APIs ([`package:js_facade_gen`](https://github.com/dart-archive/js_facade_gen), [`package:js_bindings`](https://pub.dev/packages/js_bindings), [`package:typings`](https://pub.dev/packages/typings)). Each contribution helped make Dart’s interop design better. To each of you out there, thank you for making this such an exciting adventure!

Finally, here we are in 2024. We released [`dart:js_interop`](https://dart.dev/interop/js-interop) in Dart 3.3 together with [`package:web`](https://dart.dev/interop/js-interop/package-web), the newest solutions for JS interop in Dart that make compiling [Flutter to Wasm](https://docs.flutter.dev/platform-integration/web/wasm) possible.

```dart
// Access via `dart:js_interop` (2024)
import 'dart:js_interop';

// Declarations use extension types, which are very similar to package:js
// declarations. The main difference: they are statically dispatched.
extension type MyObject._(JSObject _) implements JSObject {
  external int get field1;
  external void set field1(int value);
  external String method2();
}

@JS()
external MyObject get myTopLevel;

void main() {
  var object = myTopLevel;
  object.field1 = 1;
  // At last, access is sound - this line fails with a type error
  // when returning from method2.
  object.method2().substring(1);
}
```


* `dart:js_interop` is a static, sound, idiomatic, expressive, and consistent form of interop based on extension types that is capable of exposing any JavaScript or browser APIs.

* `package:web` uses `dart:js_interop` to do what `dart:html` once did 13 years ago, but in a way that is supported both in JavaScript and WasmGC.

Today, we are excited to celebrate a new form of Dart/JS interop and the future it enables. Knowing our past, we are certain this isn’t the end of the journey, but an exciting point in our history.

We can’t wait to see what you’ll build with it!

