#panic-hook #front-end #browser #user

browser-panic-hook

A panic hook for frontend applications

2 unstable releases

0.2.0 Jun 2, 2023
0.1.0 Jun 2, 2023

#725 in WebAssembly

Download history 267/week @ 2024-04-09 415/week @ 2024-04-16 208/week @ 2024-04-23 68/week @ 2024-04-30 96/week @ 2024-05-07 148/week @ 2024-05-14 134/week @ 2024-05-21 126/week @ 2024-05-28 255/week @ 2024-06-04 233/week @ 2024-06-11 289/week @ 2024-06-18 302/week @ 2024-06-25 259/week @ 2024-07-02 318/week @ 2024-07-09 447/week @ 2024-07-16 314/week @ 2024-07-23

1,370 downloads per month

Apache-2.0

68KB
197 lines

Browser Panic Hook

CI GitHub release (latest SemVer) crates.io docs.rs

A go-to panic handler for WebAssembly based Rust application is console_error_panic_hook, which does the job, but isn't really end user-friendly.

In the case of running the WebAssembly application as a frontend application, we do have the browser which can help interacting with the user, so why not leverage it.

That is what this crate does, failing in style:

Screenshot of an example

Presentation

The panic is also always still logged to the console as a first step. As it might happen that running the panic handler might run into trouble as well.

Next, it depends on what presentation mode you register. There is a Basic one, which takes over the body of the document and renders some simple HTML structure, including some CSS class names. In combination with an existing stylesheet, this may already be enough.

The CustomBody mode allow to provide a function, which renders the full body. This can be used to create more customized output for frameworks like PatternFly or Bootstrap.

Everything boils down to a trait (PresentationMode), for which you can also provide a custom implementation.

Just note, your application is already panicking, so you should try to keep it simple, or rely on some basic browser functionality.

Usage

In any case, you need to add this crate a dependency to your project, and register the panic handler. Registering can be as easy as:

pub fn main() -> Result<(), JsValue> {
    browser_panic_hook::set_once_default();

    // run your application ...
    Ok(())
}

You can also use a more customized variant:

pub fn main() -> Result<(), JsValue> { 
    browser_panic_hook::set_once(|| {
        browser_panic_hook::CustomBody(Box::new(|details| {
            // render new body
            format!("")
        }))
    });
 
    // run your application ...
    Ok(())
}

More complete examples can be found in the examples folder.

Yew

Yew already sets a default panic hook. This can be overridden using:

pub fn main() -> Result<(), JsValue> {
    // provide a custom panic hook
    yew::set_custom_panic_hook(Basic.into_panic_hook());
    // run the application
    yew::Renderer::<app::Application>::new().render();
    Ok(())
}

Future improvements

Additional improvements could be done, like:

  • Call a diagnostic endpoint with the panic information
  • Create a mode which overlays instead of replaces the HTML body
  • Allow adding additional, application specific, HTML (like "click here to report the error")
  • For sure some more …

Dependencies

~6.5–8.5MB
~169K SLoC