docs: merged 0.4.x with next docs

docs/0.4.x/en-US/reference/faq.md

@@ -2,28 +2,9 @@
 
 This document is a list of common pitfalls and known bugs in Perseus, and will be updated regularly. If you're having an issue with Perseus, check through this list to see if your problem already has a solution.
 
-## `perseus serve` fails with no error message on Arch Linux
-
-If you're running Arch Linux or a derivative (e.g. Manjaro), you're very likely to encounter a bug in which `perseus serve` stops with no error messages whatsoever, and your app doesn't build properly. This is tracked by [issue #78](https://github.com/arctic-hen7/perseus/issues/78), and is due to an issue in OpenSSL that causes a segmentation fault in `wasm-pack` (see [this issue](https://github.com/rustwasm/wasm-pack/issues/1079)). Right now, the only solution to this is to downgrade `wasm-pack` by running `cargo install wasm-pack --version "0.9.1"`, which seems to fix the problem.
-
 ## I'm getting JSON error messages...
 
-If an error occurs during `perseus serve`, it's very possible that you'll get error messages in JSON, which are utterly unreadable. This is because of the way the server is run, the Perseus CLI needs a JSON output so that it can figure out where the server binary is. You can access the human-readable logs by [snooping](:reference/snooping) on the output though, which you can do by running `perseus snoop serve` (but make sure you've run `perseus build` first).
-
-## Perseus doesn't work on an M1 Mac
-
-Pending [this PR](https://github.com/rustwasm/wasm-pack/pull/1088), `wasm-pack` doesn't support the M1 Mac, which means Perseus fails. However, you can easily fix this by using the fix explained [here](https://github.com/arctic-hen7/perseus/issues/89), which entails adding the following to `.perseus/Cargo.toml` (you don't need it in your app's, just in `.perseus/`):
-
-```toml
-[package.metadata.wasm-pack.profile.release]
-wasm-opt = false
-```
-
-This will disable optimizations for your Wasm bundle, which prevents this issue from occurring. Note however that you'll end up with very large bundles if you compile on your M1 Mac. Again though, this issue is set to be fixed very soon.
-
-## I want to apply X to my `Cargo.toml`, but it doesn't work
-
-Perseus has a rather unique code structure that will foil most attempts at modifying your own `Cargo.toml`. For example, if you wanted to change the `codegen_units` in the release profile of your app, you couldn't do this in your own `Cargo.toml`, it would have no effect. The reason for this is that the code your write is actually a library that's imported by the CLI's engines, so any custom configuration has to be made directly on the engines. In other words, you'll need to apply your changes on `.perseus/Cargo.toml` instead. You can also apply customizations on the server and the builder, which are separate crates under `.perseus/`. Note that modifying `.perseus/` and retaining your changes requires [ejecting](:reference/ejecting), or you could [write a plugin](:reference/plugins/writing) if it's a change you make a lot.
+If an error occurs during `perseus serve`, it's very possible that you'll get error messages in JSON, which are utterly unreadable. This is because of the way the server is run, the Perseus CLI needs a JSON output so that it can figure out where the server binary is. You can access the human-readable logs by 'snooping' on the output though, which you can do by running `perseus snoop serve` (but make sure you've run `perseus build` first).
 
 ## Cargo is putting out strange errors...
 
@@ -40,10 +21,6 @@ mv registry old
 
 That will archive the `git/` and `registry/` folders in `~/.cargo/`, which should resolve any corruptions. Then, just run `cargo build` in your project (after `perseus clean && cargo clean`) and everything should work! If not and you have no idea what's going on, feel free to ask on our [Discord server](https://discord.com/invite/GNqWYWNTdp)!
 
-## I want to disable a Perseus default feature, but it's not doing anything
-
-If you add `default-features = false` to your `Cargo.toml` and expect Perseus to adapt accordingly, you're in for a bit of a shock unfortunately! The reason for this is that the Perseus CLI isn't (yet) smart enough to know you've done this, so it will completely ignore you and press on with default features in the engine, and those settings will override your own. To disable default features, you'll need to also make these changes in `.perseus/Cargo.toml`, `.perseus/builder/Cargo.toml`, and `.perseus/server/Cargo.toml` (and you'll need to [eject](:reference/ejecting) to save your changes). In future versions, the CLI will be able to detect your preferences for this and update accordingly.
-
 ## How do I get the bleeding-edge version of the CLI?
 
 If you've tried to download the bleeding-edge version of the CLI with `cargo install`, using a Git dependency on the `perseus-cli` package, you've probably been hit with a whole host of errors that don't make a whole lot of sense! The reason for this is that the Perseus CLI depends on including a folder that's not checked into Git (the engine, `.perseus/`, but transformed in various ways). That means that, to build the CLI, you need to have that folder available, which `cargo install` isn't smart enough to do yet from a Git dependency.
@@ -55,3 +32,9 @@ The way you get around this is unfortunately inconvenient, you'll have to manual
 Perseus v0.3.x uses Sycamore v0.7.x, which still has several hydration bugs, so there are multiple things that won't work with it yet. In fact, as a general rule, if you're getting weird layout bugs that make absolutely no logical sense, try disabling hydration, it will often fix things at the moment.
 
 Sycamore v0.8.0 has been released in beta to solve these problems and many others, though it also radically changes Sycamore's API, and the upgrade of Perseus (a very large and complex system) is still ongoing. Once this is complete, Perseus v0.4.0 will be released in beta, and that should fix all current hydration bugs. In other words, if you have an error solely due to hydration at the moment, you should disable it for now and wait until Perseus v0.4.0, which will hopefully fix it. When that's released, if you're still experiencing problems with hydration, please let us know!
+
+## How do I use `[perseus::browser]` and `#[perseus::engine]` in my app?
+
+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).
+
+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.

docs/0.4.x/en-US/reference/migrating.md

@@ -2,21 +2,21 @@
 
 Perseus v0.4.x added several breaking changes, along with a full migration to Sycamore v0.8.x, which requires some rewriting of your view code, most of which is covered on the [Sycamore website](https://sycamore-rs.netlify.app).
 
-**Warning:** Perseus v0.4.x is still in beta, so there may still be several bugs! Additionally, both the Sycamore and Perseus APIs are potentially subject to significant changes during the beta period, so you may be making major changes to your app quite often.
+**Warning:** Perseus v0.4.x is still in beta, so there may still be several bugs! Additionally, both the Perseus API is potentially subject to significant changes during the beta period, so you may be making major changes to your app quite often.
 
-1. Update your `Cargo.toml` dependencies for `perseus` to `0.4.0-beta.8`.
+1. Restructure your `Cargo.toml` to reflect the new dependency-splitting format (which splits engine-side dependencies from those only needed in the browser). See [here](https://github.com/framesurge/perseus/tree/main/examples/core/basic/Cargo.toml) for an example. Note that this will involve adding a server integration for use, like `perseus-warp`.
 2. Upgrade the Perseus CLI with `cargo install perseus-cli --version 0.4.0-beta.8`.
-3. Run `perseus clean` to remove the old `.perseus/` directory.
-4. Update your view code for Sycamore's new version (mostly including adding a `cx` parameter as the first argument of every function that returns a `View<G>`).
+3. Delete the old `.perseus/` directory (this is no longer needed).
+4. Rename your `lib.rs` file to `main.rs`.
+5. Update each error page instantiation function to provide, as another argument, a function that returns a Sycamore `View<G>` for the document metadata of that error page (e.g. title).
+6. Change the `#[perseus::main]` attribute on the function in `main.rs` to be `#[perseus::main(perseus_warp::dflt_server)]` (replace `perseus_warp` with whatever server integration you decide to use).
+7. Update your view code for Sycamore's new version (mostly including adding a `cx` parameter as the first argument of every function that returns a `View<G>`).
+8. Update your code for any smaller breaking changes that might affect you, as per the [changelog](https://github.com/framesurge/perseus/blob/main/CHANGELOG.md).
+9. Run `cargo update` and then `perseus build` to get everything up to date and e
+ensure that your app works! (This might take a while the first time.)
 
 ## If You've Ejected
 
-If you were running Perseus v0.3.x and had ejected, here are the steps you should take in addition to the above.
+If you were running Perseus v0.3.x and had ejected, your app's structure is likely to change significantly, as Perseus v0.4.x no longer uses `.perseus/`! For example, you can now directly modify the server Perseus runs, allowing you to add your own API routes trivially! (See the [custom server example](https://github.com/framesurge/tree/main/examples/core/custom_server) for details.)
 
-1. Rename `.perseus/` to `.perseus.old/`.
-2. Run `perseus build` to create a new `.perseus/` directory.
-3. Apply your changes to the new directory.
-4. Delete `.perseus.old/` when you're done.
-5. Confirm everything works with `perseus serve`.
-
-This may seem arduous, but v0.4.x includes extreme restructuring of the innards in `.perseus/`, and it's typically simpler to re-apply your own changes to the new system than it is to apply Perseus' updates to your existing directory (though you could do this if you really wanted).
+The migration process you follow will be highly unique to your app's structure, though most common use-cases should be covered y the custom server example, linked above. If you need any further help, feel free to ask in GitHub discussions or on [Discord](https://discord.com/invite/GNqWYWNTdp), and we're happy to help in any way we can!