Skip to content

Commit f2447df

Browse files
fitzgenfitzgen
committed
Announcing the web-sys crate!
1 parent 0145f0e commit f2447df

File tree

1 file changed

+181
-0
lines changed

1 file changed

+181
-0
lines changed

‎_posts/2018-09-26-announcing-web-sys.md

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
title: "Announcing the web-sys crate!"
3+
---
4+
5+
**We are pleased to announce the first release of [the `web-sys`
6+
crate!](https://rustwasm.github.io/wasm-bindgen/web-sys/index.html) It provides
7+
raw bindings to all the Web's APIs: everything from DOM manipulation to WebGL to
8+
Web Audio to timers to `fetch` and more!**
9+
10+
Almost three months ago, we laid out [our vision for
11+
`wasm-bindgen`:](../../07/02/vision-for-wasm-bindgen.html)
12+
13+
> We are building a shared foundation for an ecosystem of Rust crates that
14+
> target JavaScript environments with `wasm-bindgen`. Sharing a foundation means
15+
> sharing raw `extern` imports. Every library that uses the Web's
16+
> `window.requestAnimationFrame` function or ECMAScript's `Object.freeze`
17+
> function shouldn't need to write the `extern` imports themselves.
18+
19+
We observed that the Web has a *huge* number of APIs and that adding support for
20+
all of them by hand would be a Sisyphean task. However, all these APIs are
21+
standardized with the same interface definition language, and we realized that
22+
we could leverage that to mechanically generate a crate containing every single
23+
Web API:
24+
25+
> All of the Web’s API types, functions, and methods are specified with
26+
> [WebIDL](https://heycam.github.io/webidl/), so we are working on a new WebIDL
27+
> frontend to `wasm-bindgen`. When the WebIDL frontend is ready, we plan on
28+
> taking the interface definitions for all the Web APIs from all their standards
29+
> and automatically generating a big `-sys` style crate from them.
30+
31+
<a style="max-width: 300px; float: right; padding: 1.5em; font-size: 80%" href="/images/new-wasm-bindgen-architecture.png">
32+
<img alt="wasm-bindgen's new architecture with a WebIDL frontend"
33+
src="/images/new-wasm-bindgen-architecture.png"/>
34+
`wasm-bindgen`'s new architecture with its WebIDL frontend.
35+
</a>
36+
37+
This plan has finally been realized in the `web-sys` crate! We added a frontend
38+
to `wasm-bindgen` that slurps in WebIDL interface definitions and emits
39+
`wasm-bindgen`'s internal abstract syntax tree (AST). This frontend is the
40+
`wasm-bindgen-webidl` crate. Once we have the AST, emitting zero-overhead Rust
41+
and JavaScript glue code to do type conversion and shepherding of function
42+
parameters and return values is the same as normal `#[wasm_bindgen]`
43+
annotations.
44+
45+
Is using WebIDL to mechanically generate glue code a new idea? Nope! This is the
46+
same battle-tested strategy that every browser engine uses to generate
47+
JavaScript-to-C++ glue code (or in [Servo's](https://servo.org/) case,
48+
JavaScript-to-Rust) for its implementation of these APIs. Furthermore, it is yet
49+
another way that `wasm-bindgen` is future-compatible with [the host bindings
50+
proposal.](https://github.com/WebAssembly/host-bindings/blob/master/proposals/host-bindings/Overview.md)
51+
The host bindings proposal will allow WebAssembly to directly call into native
52+
DOM methods without going through a JavaScript shim, promising to eventually
53+
unlock even-faster-than-JS DOM performance since calls from wasm can be
54+
statically validated to type check once at compilation time, rather than
55+
dynamically on every single call. The proposal suggests that the interface to
56+
the host's bindings be generated mechanically from WebIDL, and we are doing
57+
exactly that.
58+
59+
<div style="clear: both"/>
60+
<style>h2, h3 { margin-top: 15px; }</style>
61+
62+
## The `js-sys` crate is 100% feature complete!
63+
64+
A related bit of news is that [the `js-sys`
65+
crate](https://rustwasm.github.io/2018/07/26/announcing-the-js-sys-crate.html)
66+
is now 100% feature complete! It contains raw bindings to every ECMAScript API
67+
(those APIs that are available both in Node.js and on the Web and any other JS
68+
environment).
69+
70+
Unlike the `web-sys` crate, these are written by hand because there is no WebIDL
71+
describing these APIs. That would have been great to have, both because it would
72+
have been easier to implement the `js-sys` crate, and because we would have
73+
avoided bugs along the way. We considered a TypeScript frontend, but did not
74+
prioritize it because TypeScript does not describe whether or not functions
75+
throw exceptions.
76+
77+
## Example Programs
78+
79+
[We have a growing list of examples of using `web-sys`, `js-sys`, and
80+
`wasm-bindgen`
81+
together!](https://rustwasm.github.io/wasm-bindgen/examples/index.html) The
82+
following programs are a small selection of these.
83+
84+
### A Simple Paint Program with 2D Canvas
85+
86+
Click and drag to draw!
87+
88+
[More information and source code.](https://rustwasm.github.io/wasm-bindgen/examples/paint.html)
89+
90+
<iframe src="https://rustwasm.github.io/wasm-bindgen/exbuild/paint/" style="min-width: 662px; min-height: 502px;"></iframe>
91+
92+
### An FM Synthesizer with Web Audio
93+
94+
This example creates an [FM
95+
synthesizer](https://en.wikipedia.org/wiki/Frequency_modulation_synthesis) using
96+
the [WebAudio
97+
API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) and
98+
`web-sys`.
99+
100+
[More information and source code.](https://rustwasm.github.io/wasm-bindgen/examples/web-audio.html)
101+
102+
<iframe src="https://rustwasm.github.io/wasm-bindgen/exbuild/webaudio/" style="width: 100%;"></iframe>
103+
104+
## Friends 💖
105+
106+
### Contributors to `web-sys` and `wasm-bindgen-webidl`
107+
108+
Huge thanks to everyone who helped build the `web-sys` crate and the Web IDL
109+
frontend for `wasm-bindgen` that made the `web-sys` crate possible!
110+
111+
- afdw
112+
- Alex Crichton
113+
- Andrew Chin
114+
- Anton Danilkin
115+
- Benjamin Kampmann
116+
- Ben Merritt
117+
- Jonathan Kingston
118+
- Julius Rakow
119+
- Michael Hoffmann
120+
- Nick Fitzgerald
121+
- R. Andrew Ohana
122+
- Richard Dodd (dodj)
123+
- Ruben Schmidmeister
124+
- Sendil Kumar N
125+
- Stephan Wolski
126+
- teovoinea
127+
- twilco
128+
- Tyler Wilcock
129+
- YUyz
130+
131+
### Contributors to `js-sys`
132+
133+
A second round of applause for everyone who contributed to the `js-sys` crate!
134+
135+
- Alexander Kryvomaz
136+
- Alex Crichton
137+
- Andrew Chin
138+
- Anton Danilkin
139+
- belfz
140+
- bokuweb
141+
- Camille TJHOA
142+
- Chris Kolodin
143+
- Craig Disselkoen
144+
- Danielle Pham
145+
- data-pup
146+
- Dimitrii Nemkov
147+
- Frazer McLean
148+
- gaurikholkar
149+
- Herman J. Radtke III
150+
- Ivan Enderlin
151+
- Jannik Keye
152+
- Joel Gallant
153+
- Johannes Henninger
154+
- Jonas Trollvik
155+
- Jonathan Sundqvist
156+
- Kevin Hoffman
157+
- kzvi
158+
- Lachezar Lechev
159+
- Liigo Zhuang
160+
- Marcin Baraniecki
161+
- Mason Stallmo
162+
- Matias Insaurralde
163+
- Matt Kraai
164+
- Matt Long
165+
- Michael Hoffmann
166+
- Nick Fitzgerald
167+
- R. Andrew Ohana
168+
- robertdurst
169+
- Roberto Huertas
170+
- Satoshi Amemiya
171+
- Sendil Kumar N
172+
- sepiropht
173+
- Stephan Renatus
174+
- Thomas Eizinger
175+
- Tim Ryan
176+
- T. Nagasawa
177+
- Tomohide Takao
178+
- toversus
179+
- Tyler Laing
180+
- Tyler Wilcock
181+
- xeqlol

0 commit comments

Comments
 (0)