1# Unstable APIs
2
3It's common for browsers to implement parts of a web API while the specification
4for that API is still being written. The API may require frequent changes as the
5specification continues to be developed, so the WebIDL is relatively unstable.
6
7This causes some challenges for `web-sys` because it means `web-sys` would have
8to make breaking API changes whenever the WebIDL changes. It also means that
9previously published `web-sys` versions would be invalid, because the browser
10API may have been changed to match the updated WebIDL.
11
12To avoid frequent breaking changes for unstable APIs, `web-sys` hides all
13unstable APIs through an attribute that looks like:
14
15```rust
16#[cfg(web_sys_unstable_apis)]
17pub struct Foo;
18```
19
20By hiding unstable APIs through an attribute, it's necessary for crates to
21explicitly opt-in to these reduced stability guarantees in order to use these
22APIs. Specifically, these APIs do not follow semver and may break whenever the
23WebIDL changes.
24
25Crates can opt-in to unstable APIs at compile-time by passing the `cfg` flag
26`web_sys_unstable_apis`. Typically the `RUSTFLAGS` environment variable is used
27to do this. For example:
28
29```bash
30RUSTFLAGS=--cfg=web_sys_unstable_apis cargo run
31```
32