You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**WARNING:** These docs are under heavy construction right now, in preparation for the release of Perseus v0.4.0, which will be, by far, the most powerful version of Perseus yet! A lot has changed though, so we *highly* recommend sticking to the v0.3.4+ docs if you're using v0.3.x, or the v0.4.x docs if you're still on one of the beta versions up to beta 11. The `next` docs (these ones) are highly incomplete, probably full of errors and typos, and have not yet been thoroughly checked. You have been warned!
6
+
5
7
Welcome to the Perseus documentation! Here, you'll find guides on how to use Perseus, as well as documentation for specific features and plenty of examples! Note that every code snippet in these docs comes from something in the [examples](https://github.com/arctic-hen7/perseus/tree/main/examples), where you can get context from real-world code.
6
8
7
9
If you like Perseus, please consider giving us a star [on GitHub](https://github.com/arctic-hen7/perseus)!
Copy file name to clipboardExpand all lines: docs/0.4.x/en-US/reference/faq.md
+18
Original file line number
Diff line number
Diff line change
@@ -38,3 +38,21 @@ Sycamore v0.8.0 has been released in beta to solve these problems and many other
38
38
These macros are simple proxies over the more longwinded `#[cfg(target_arch = "wasm32")]` and the negation of that, respectively. They can be easily applied to functions, `struct`s, and other 'block'-style items in Rust. However, you won't be able to apply them to statements (e.g. `call_my_function();`) , since Rust's [proc macro hygiene](https://github.com/rust-lang/rust/issues/54727) doesn't allow this yet. If you need to use stable Rust, you'll have to go with the longwinded versions in these places, or you could alternatively create a version of the functions you need to call for the desired platform, and then a dummy version for the other that doesn't do anything (effectively moving the target-gating upstream).
39
39
40
40
The best solution, however, is to switch to nightly Rust (`rustup override set nightly`) and then add `#![feature(proc_macro_hygiene)]` to the top of your `main.rs`, which should fix this.
41
+
42
+
## I'm getting really weird errors with a page's `<head>`...
43
+
44
+
Alright, this can mean about a million things. There is one that could be known to be Perseus' fault though: if you go to a page in your app, then reload it, then go to another page, and then navigate *back* to the original page (using a link inside your app, *not* your browser's back button), and there are problems with the `<head>` that weren't there before, then you should disable the `cache-initial-load` feature on Perseus, since Perseus is having problems figuring out how your `<head>` works. Typically, a delimiter `<meta itemprop="__perseus_head_end">` is added to the end of the `<head>`, but if you're using a plugin that's adding anything essential after this, that will be lost on transition to the new page. Any advanced manipulation of the `<head>` at runtime could also cause this. Note that disabling this feature (which is on by default) will prevent caching of the first page the user loads, and it will have to be re-requested if they go back to it, which incurs the penalty of a network request.
45
+
46
+
## I'm getting a 'mismatched render backends' error
47
+
48
+
This is a very rare kind of error that Perseus will emit if it knows that running your app in its current state will cause undefined behavior: it's a safeguard against far worse things happening. if you're using the reference pattern of managing your templates and/or capsules, where you define them in `lazy_static!`s, and then bring those into `.template_ref()`/`.capsule_ref()`, this problem is almost certainly caused by your using the incorrect *render backend generic*. In those statics, you have to specify a concrete value for that `G: Html` you see floating around the place. You might have chosen `DomNode`, or `SsrNode`, or maybe even `HydrateNode`, but each of these is only valid sometimes! Perseus internally knows when it uses each one, and it provides a clever little type alias that can handle all this for you: `PerseusNodeType`. If you use that, this error shoudl go away, adn your app should work perfectly!
49
+
50
+
Alternately, this error can occur if you try to do something very inadvisable, like putting a widget in a `view!` that you try to `render_to_string` on the browser-side. In fact, any attempt to render to a string in the browser that uses widgets is almost certain to trigger this exact error. This is because `PerseusNodeType` automatically resolves to `DomNode`/`HydrateNode` (depending on whether or not you've enabled the `hydrate` feature) on the browser-side, because Perseus doesn't need to do any server-side rendering there (unsurprisingly). That means, when you bring in a widget that's defined as a `lazy_static!` using `PerseusNodeType`, your `View` might be a `View<SsrNode>`, but the `MY_WIDGET.widget()` function will take that `SsrNode`, hold it for a moment, and check the type of itself, which it will find to be `PerseusNodeType`. Since `DomNode != SsrNode` and `HydrateNode != SsrNode`, it will find that you're trying to use a browser-side widget in a server-side rendered view, which is a type mismatch. Normally, this sort of thing could be caught by Rust at compilation-time, but Perseus uses some transmutes internally to make it safe to use `PerseusNodeType`, as long as it lines up with the actual type of the `View` being rendered. if you try to server-side render in the browser though, the types don't line up, and Perseus has the choice of either panicking or causing undefined behavior. To maintain safety, it panics.
51
+
52
+
Note that this doesn't mean it's actually impossible to server-side render a widget on the browser-side, you can use the functional pattern to do this easily. Rather than using `MY_CAPSULE.widget()`, just use `crate::path::to::my::widget::get_capsule().widget()`, because `get_capsule()` is generic over `G: Html` meaning it will just work with Rust's normal typing system.
53
+
54
+
If you're still getting this error, and none of these solutions make sense with what you're doing, then you've possibly encountered a rather serious Perseus bug, which we'd like to know about so we can fix it! Please report it [on GitHub](https://github.com/framesurge/perseus/issues/new/choose).
55
+
56
+
## Problem binding to `http://localhost:3100`
57
+
58
+
This means another instance of Persues is already running. The reason this talks about <http://localhost:3100> rather than port 8080 is because 3100 is where the live reload server runs by default.
0 commit comments