diff --git a/docs/next/en-US/first-app/installation.md b/docs/next/en-US/first-app/installation.md index 43f63c0cdf..011b6b9135 100644 --- a/docs/next/en-US/first-app/installation.md +++ b/docs/next/en-US/first-app/installation.md @@ -33,3 +33,13 @@ Next, put the following in your app's `Cargo.toml`: The main things to pay attention to here are the dependencies, which are laid out differently from most Rust apps. Perseus is built in two parts: the *engine-side*, which is responsible for prerendering your pages, serving content, exporting your app, etc.; and the *client-side*, which runs inside a user's browser to make Perseus interactive, handling routing, interactivity, etc. The engine-side of your app will build to whatever target you compile it for, like `x86_64-unknown-linux-gnu`, which you would have on an OS like Ubuntu. This means Rust will translate your code into machine code that computers with that kind of processor and OS can understand (if you were running on an M1 Mac, the target would be quite different). The browser has its own sepaarate target, which ensures that you don't have to compile your code for every possible device that a user might view it on --- the browser takes care of all that, and runs Wasm, which is its own special language that Rust can translate itself into. That all means that there are some features that don't belong in the browser (like building your app), and others that don't belong in the engine (like managing routing), so Perseus *target-gates* these, using Rust's `#[cfg(..)]` macro to make sure that certain things are only compiled at the right time. This reduces compilation times, and also slims down the bundles for both the engine and the browser (because they contain no unnecessary code). Sometimes, you'll want to do this in your own code as well, like if you have some function that should only run on the browser-side. Remember how we set up that `rustflags` key in `.cargo/config.toml`? Well, that's so you can use it just like this! If you want code to only be compiled for the browser, you put `#[cfg(client)]` on top of it, and you can use `#[cfg(engine)]` to do the same for the engine. You'll usually see this in Rust code, but your `Cargo.toml` can use it too for declaring dependencies that will only be used on one particular target. Here, we're making sure to bring in `perseus` everywhere, but `perseus-warp` (our server integration) should only be used on the engine-side. When you bring in a new dependency, think about whether it has to be available on the browser-side, because it often doesn't. For example, you could bring in the `regex` crate to automatically highlight any technical terms in a documentation site, but you can actually do that solely on the engine-side if you handle all that in the state generation process (which we'll get to). This avoids bringing the `regex` crate into the browser, which keeps your `.wasm` bundle nice and slim. A smaller Wasm bundle means it can be transferred over the network more quickly, which means faster page loads. + +As for the actual dependencies themselves, here's what each one is for: + +- `perseus`: this framework +- `sycamore`: the library that Perseus builds on, which you'll use to write views +- `serde` and `serde_json`: serialization/deserialization libraries you'll need to help Perseus transmit your pages over the internet +- `tokio` (engine-only): an `async` runtime used by Perseus, which your code is responsible for instantiating (but 99% of the time, you'll do that with a helper macro); we select certain features to improve performance and reduce compilation times +- `perseus-axum`: a server integration that will serve your pages to users + +A basic Perseus app won't have any client-side dependencies, and you can omit that empty section if you like, but it's included here for completeness.