blitz_script/lib.rs
1//! JavaScript execution on top of Blitz
2//!
3//! This crate implements a [`ScriptDocument`]: a wrapper around a [`BaseDocument`](blitz_dom::BaseDocument)
4//! which can execute the JavaScript contained in (or referenced by) the document's `<script>` tags
5//! using the [Boa](https://boajs.dev) JavaScript engine, and which exposes JavaScript DOM APIs
6//! (`document`, elements, events, timers, etc) backed by `blitz-dom` to the scripts it runs.
7//!
8//! It is capable of running real-world JavaScript frameworks such as [Preact](https://preactjs.com/).
9//!
10//! ### Modules
11//!
12//! `<script type="module">` is parsed in module goal and its imports are
13//! resolved and fetched through the same [`ScriptFetcher`] as classic
14//! `<script src>`, so a module graph blocks the document thread the same way a
15//! classic script already does. `<script type="importmap">`, `import.meta.url`,
16//! dynamic `import()` and JSON modules (`with { type: "json" }`) are supported;
17//! import-map `integrity` and module workers are not.
18//!
19//! ### Example
20//!
21//! ```rust
22//! use blitz_script::ScriptDocument;
23//! use blitz_dom::DocumentConfig;
24//!
25//! let mut doc = ScriptDocument::from_html(
26//! r#"
27//! <div id="root"></div>
28//! <script>
29//! const el = document.createElement("h1");
30//! el.textContent = "Hello from JS";
31//! document.getElementById("root").appendChild(el);
32//! </script>
33//! "#,
34//! DocumentConfig::default(),
35//! );
36//! doc.execute_scripts();
37//! ```
38
39#![allow(clippy::collapsible_if)]
40
41#[cfg(feature = "debug-control")]
42mod debug_control;
43mod document;
44mod dom;
45mod event_handler;
46mod fetch;
47mod module;
48mod runtime;
49pub mod script_stats;
50mod state;
51mod timers;
52
53#[cfg(feature = "debug-control")]
54pub use debug_control::DebugController;
55pub use document::ScriptDocument;
56pub use fetch::{DefaultScriptFetcher, FetchError, ScriptFetcher};