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
Copy file name to clipboardExpand all lines: README.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,7 @@ Support every major rendering strategy and provide developers the ability to eff
22
22
23
23
## Motivation
24
24
25
-
There is a sore lack of Rust frameworks for frontend development that support more than just SPAs and client-side rendering, and so Perseus was born. We need something like NextJS for WASM.
25
+
There is a sore lack of Rust frameworks for frontend development that support more than just SPAs and client-side rendering, and so Perseus was born. We need something like NextJS for Wasm.
When you use the integration, you'll have to define a few options to tell it what exactly to serve. Specifically, you'll need to tell it where your `index.html` file, your JS bundle, and your WASM bundle all are. In addition, you'll need to a provide it with a template map (which you'll often define a getter function for as above).
55
+
When you use the integration, you'll have to define a few options to tell it what exactly to serve. Specifically, you'll need to tell it where your `index.html` file, your JS bundle, and your Wasm bundle all are. In addition, you'll need to a provide it with a template map (which you'll often define a getter function for as above).
56
56
57
57
Also, because this plugs into an existing server, you have full control over hosting options, like the port to be used!
Copy file name to clipboardExpand all lines: docs/src/serving.md
+18-18
Original file line number
Diff line number
Diff line change
@@ -1,33 +1,33 @@
1
1
# Serving
2
2
3
-
*You only need this page if you're not using the Perseus CLI, which performs this process for you!*
3
+
_You only need this page if you're not using the Perseus CLI, which performs this process for you!_
4
4
5
5
Having generated a large number of static files, you'll need a system to host your files for you! Due to the dynamic nature of some rendering strategies, Perseus needs to be involved in this process (for executing request-time logic), and so it provides a simple API interface for serving pages.
6
6
7
7
Perseus aims to be agnostic as to what framework you use to host your files, and any framework that gives you access to request headers and wildcard paths should work (in other words, any framework worth its salt).
8
8
9
9
If you're using one of our supported integrations, you don't have to bother with this page, nearly all of it can be done for you!
10
10
11
-
-[Actix Web](./integrations/actix-web.md)
12
-
-*More coming soon...*
11
+
-[Actix Web](./integrations/actix-web.md)
12
+
-_More coming soon..._
13
13
14
14
## Endpoints
15
15
16
16
Here are the endpoints that a server for Perseus must serve:
17
17
18
-
-`/.perseus/page/*` – used to serve the JSON data that the app shell needs to render a page (`*` should be extractable as a filename, e.g. `{filename:.*}` in Actix Web)
19
-
-`/.perseus/bundle.js` – the JavaScript bundle file that calls your WASM code (see [tutorial on building your first app](./tutorials/first_app/intro.md))
20
-
-`/.perseus/bundle.wasm` – the WASM bundle file that contains your code (see [tutorial on building your first app](./tutorials/first_app/intro.md))
21
-
-`*` (anything else) – any page that the user actually requests, which will return the app shell to do the heavy lifting (or more accurately an HTML file that includes the bundle)
18
+
-`/.perseus/page/*` – used to serve the JSON data that the app shell needs to render a page (`*` should be extractable as a filename, e.g. `{filename:.*}` in Actix Web)
19
+
-`/.perseus/bundle.js` – the JavaScript bundle file that calls your Wasm code (see [tutorial on building your first app](./tutorials/first_app/intro.md))
20
+
-`/.perseus/bundle.wasm` – the Wasm bundle file that contains your code (see [tutorial on building your first app](./tutorials/first_app/intro.md))
21
+
-`*` (anything else) – any page that the user actually requests, which will return the app shell to do the heavy lifting (or more accurately an HTML file that includes the bundle)
22
22
23
23
## Usage
24
24
25
25
This example shows what would be done to acquire a page for any framework. You'll need to have access to these data to get a page:
26
26
27
-
- The page path the user requested, e.g. `/post/test` for a request to `/.perseus/page/post/test`
28
-
- Data about the HTTP request the user sent (see below)
29
-
- A map of templates produced with [`get_templates_map!`]() (API docs WIP)
30
-
- A [config manager](./config_managers.md)
27
+
-The page path the user requested, e.g. `/post/test` for a request to `/.perseus/page/post/test`
28
+
-Data about the HTTP request the user sent (see below)
29
+
-A map of templates produced with [`get_templates_map!`]() (API docs WIP)
30
+
-A [config manager](./config_managers.md)
31
31
32
32
```rust,no_run,no_playground
33
33
use perseus::{get_page};
@@ -46,7 +46,7 @@ match page_data {
46
46
47
47
## Request Data
48
48
49
-
Perseus needs access to information about HTTP requests so it can perform tasks related to the *request state* strategy, which provides access to headers and the like. Internally, Perseus uses [`http::Request`](https://docs.rs/http/0.2.4/http/request/struct.Request.html) for this, with the body type `()` (payloads are irrelevant in requests that ask for a page at a URL).
49
+
Perseus needs access to information about HTTP requests so it can perform tasks related to the _request state_ strategy, which provides access to headers and the like. Internally, Perseus uses [`http::Request`](https://docs.rs/http/0.2.4/http/request/struct.Request.html) for this, with the body type `()` (payloads are irrelevant in requests that ask for a page at a URL).
50
50
51
51
Unfortunately, different web server frameworks represent request data differently, and so you'll need to convert from your framework's system to `http`'s. When integrations are ready, this will be done for you!
// Any custom data should therefore be sent in headers (if you're doing that, consider a dedicated API)
78
78
.body(())
79
79
.map_err(|err|format!("converting actix web request to perseus-compliant request failed: '{}'", err))?;
80
-
80
+
81
81
Ok(req)
82
82
}
83
83
```
84
84
85
85
Notably, the data that need to be converted are:
86
86
87
-
- Headers
88
-
- URI to which the request was sent
89
-
- HTTP method (subject to change in future Perseus versions, currently `GET`)
90
-
- HTTP version used
87
+
-Headers
88
+
-URI to which the request was sent
89
+
-HTTP method (subject to change in future Perseus versions, currently `GET`)
90
+
-HTTP version used
91
91
92
-
Note that mis-converting any of these data will not affect Perseus (which doesn't require any of them to function), only your own code. So if you have no intention of using the *request state* strategy in your app, you could theoretically just parse an empty request to Perseus like so:
92
+
Note that mis-converting any of these data will not affect Perseus (which doesn't require any of them to function), only your own code. So if you have no intention of using the _request state_ strategy in your app, you could theoretically just parse an empty request to Perseus like so:
Copy file name to clipboardExpand all lines: docs/src/tutorials/first_app/setup.md
+4-2
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ After you've done this, make sure everything works by running `cargo` in a termi
10
10
11
11
## Build Tools
12
12
13
-
Perseus is built on top of WASM (WebAssembly), which basically lets you use programming languages other than JavaScript to build websites/webapps. That tech is *really* complicated, and you'll need two particular build tools to make your code work.
13
+
Perseus is built on top of Wasm (WebAssembly), which basically lets you use programming languages other than JavaScript to build websites/webapps. That tech is _really_ complicated, and you'll need two particular build tools to make your code work.
14
14
15
15
The first one is [`wasm-pack`](), which helps to compile your Rust code to WebAssembly (sort of like how you'd compile code normally, but specially for the browser). You can install it with this command:
16
16
@@ -20,12 +20,14 @@ cargo install wasm-pack
20
20
21
21
Now, you should be able to type `wasm-pack` in your terminal to get another help page!
22
22
23
-
The next tool is one you might be familiar with if you're coming from the JavaScript world: [Rollup](https://rollupjs.org). Rollup is a bundling tool for JavaScript, and it works really nicely with WASM. If you loathe JavaScript with a passion, don't worry, the only JavaScript in Perseus just invokes your (infinitely superior) Rust code! You can install Rollup with the following command:
23
+
The next tool is one you might be familiar with if you're coming from the JavaScript world: [Rollup](https://rollupjs.org). Rollup is a bundling tool for JavaScript, and it works really nicely with Wasm. If you loathe JavaScript with a passion, don't worry, the only JavaScript in Perseus just invokes your (infinitely superior) Rust code! You can install Rollup with the following command:
0 commit comments