web_panic_report 0.3.0

A panic hook which replaces an HTML element with a bug report form.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

<div align="center">

# Web Panic Report

**A panic hook which replaces an HTML element with a bug report form.**

[![Discord](https://img.shields.io/discord/913957940560531456.svg?label=Loopy&logo=discord&logoColor=ffffff&color=ffffff&labelColor=000000)](https://discord.gg/zrjnQzdjCB)
[![MIT/Apache 2.0](https://img.shields.io/badge/license-MIT%2FApache-blue.svg)](#license)
[![Build status](https://github.com/loopystudios/web_panic_report/workflows/CI/badge.svg)](https://github.com/loopystudios/web_panic_report/actions)
[![dependency status](https://deps.rs/repo/github/loopystudios/web_panic_report/status.svg)](https://deps.rs/repo/github/loopystudios/web_panic_report)
[![Crates.io](https://img.shields.io/crates/v/web_panic_report.svg)](https://crates.io/crates/web_panic_report)
[![Docs](https://img.shields.io/docsrs/web_panic_report)](https://docs.rs/web_panic_report)

</div>

> [!WARNING]
> The goal of this project is NOT to provide a full-fledge error reporting and analytics, only to help provide a framework to report panic conditions.

Quickstart to run demo:

```shell
# Make sure the Rust toolchain supports the wasm32 target
rustup target add wasm32-unknown-unknown

# Install `wasm-server-runner` for the example
cargo install wasm-server-runner

WASM_SERVER_RUNNER_CUSTOM_INDEX_HTML=examples/index.html cargo run --target wasm32-unknown-unknown --example simple
```

There is also a web demo [available here](https://loopystudios.github.io/web_panic_report).

![Demo](image.png)

## Usage

> [!IMPORTANT]
> On release mode, debug symbols are stripped. You will need to enable them manually if you want useful stack traces for production builds.
>
> Add the following to your `Cargo.toml`
>
> ```toml
> [profile.release]
> debug = true
> ```

Ensure your web page is served with a container element that will be replaced with the bug report form.

```html
<body>
  <div id="my-container" style="width: 400px; height: 400px;">
    /** Content that is replaced here on panic, like a game canvas */
  </div>
</body>
```

Then, set the panic hook at the beginning of your program on web.

```rust
fn main() {
    #[cfg(target_arch = "wasm32")]
    web_panic_report::set_default_hook_with("my-container", |panic_info| {
        // Send the panic info to your backend here.
        // This is triggered when the user clicks "Send Report"
    });
}
```

You can also use a custom bug report form. See the [custom example](examples/custom.rs).

## Alternatives

- [`console_error_panic_hook`](https://github.com/rustwasm/console_error_panic_hook) - Only outputs stack trace to the console.

## Minimum supported Rust Version (MSRV)

This version of Web Panic Report has been verified to compile with **Rust 1.75** and later.

Future versions of Web Panic Report might increase the Rust version requirement.
It will not be treated as a breaking change and as such can even happen with small patch releases.

<details>
<summary>Click here if compiling fails.</summary>

As time has passed, some of Web Panic Report's dependencies could have released versions with a higher Rust requirement.
If you encounter a compilation issue due to a dependency and don't want to upgrade your Rust toolchain, then you could downgrade the dependency.

```sh
# Use the problematic dependency's name and version
cargo update -p package_name --precise 0.1.1
```

</details>

## Community

All Loopy projects and development happens in the [Loopy Discord](https://discord.gg/zrjnQzdjCB). The discord is open to the public.

Contributions are welcome by pull request. The [Rust code of conduct](https://www.rust-lang.org/policies/code-of-conduct) applies.

## License

Licensed under either of

- Apache License, Version 2.0
   ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license
   ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option

## Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.