Unstable APIs - The `wasm-bindgen` Guide

# Unstable APIs

It's common for browsers to implement parts of a web API while the specification for that API is still being written. The API may require frequent changes as the specification continues to be developed, so the WebIDL is relatively unstable.

This causes some challenges for `web-sys` because it means `web-sys` would have to make breaking API changes whenever the WebIDL changes. It also means that previously published `web-sys` versions would be invalid, because the browser API may have been changed to match the updated WebIDL.

To avoid frequent breaking changes for unstable APIs, `web-sys` hides all unstable APIs through an attribute that looks like:

    #![allow(unused)]
    fn main() {
    #[cfg(web_sys_unstable_apis)]
    pub struct Foo;
    }

By hiding unstable APIs through an attribute, it's necessary for crates to explicitly opt-in to these reduced stability guarantees in order to use these APIs. Specifically, these APIs do not follow semver and may break whenever the WebIDL changes.

Crates can opt-in to unstable APIs at compile-time by passing the `cfg` flag `web_sys_unstable_apis`.

Typically the `RUSTFLAGS` environment variable is used to do this. For example:

    RUSTFLAGS=--cfg=web_sys_unstable_apis cargo run

Alternatively, you can create a cargo config file to set its rustflags:

Within `./.cargo/config.toml`:

    [build]
    rustflags = ["--cfg=web_sys_unstable_apis"]