web-sys Overview

The web-sys crate has this file and directory layout:

.
├── build.rs
├── Cargo.toml
├── README.md
├── src
│   └── lib.rs
└── webidls
    └── enabled
        └── ...

webidls/enabled/*.webidl

These are the WebIDL interfaces that we will actually generate bindings for (or at least bindings for some of the things defined in these files).

build.rs

The build.rs invokes wasm-bindgen's WebIDL frontend on all the WebIDL files in webidls/enabled. It writes the resulting bindings into the cargo build's out directory.

src/lib.rs

The only thing src/lib.rs does is include the bindings generated at compile time in build.rs. Here is the whole src/lib.rs file:

#![allow(unused)]
fn main() {
//! Raw API bindings for Web APIs
//!
//! This is a procedurally generated crate from browser WebIDL which provides a
//! binding to all APIs that browsers provide on the web.
//!
//! This crate by default contains very little when compiled as almost all of
//! its exposed APIs are gated by Cargo features. The exhaustive list of
//! features can be found in `crates/web-sys/Cargo.toml`, but the rule of thumb
//! for `web-sys` is that each type has its own cargo feature (named after the
//! type). Using an API requires enabling the features for all types used in the
//! API, and APIs should mention in the documentation what features they
//! require.

#![doc(html_root_url = "https://docs.rs/web-sys/0.3")]
#![no_std]
#![allow(deprecated)]

extern crate alloc;

mod features;
#[allow(unused_imports)]
pub use features::*;

pub use js_sys;
pub use wasm_bindgen;

/// Getter for the `Window` object
///
/// [MDN Documentation]
///
/// *This API requires the following crate features to be activated: `Window`*
///
/// [MDN Documentation]: https://developer.mozilla.org/en-US/docs/Web/API/Window
#[cfg(feature = "Window")]
pub fn window() -> Option<Window> {
    use wasm_bindgen::JsCast;

    js_sys::global().dyn_into::<Window>().ok()
}
}

Cargo features

When compiled the crate is almost empty by default, which probably isn't what you want! Due to the very large number of APIs, this crate uses features to enable portions of its API to reduce compile times. The list of features in Cargo.toml all correspond to types in the generated functions. Enabling a feature enables that type. All methods should indicate what features need to be activated to use the method.