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_variables)]
#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