Skip to content

Commit

Permalink
chore: fixed all detected spelling mistakes
Browse files Browse the repository at this point in the history
  • Loading branch information
arctic-hen7 committed Oct 11, 2022
1 parent b9f089c commit e678d44
Show file tree
Hide file tree
Showing 30 changed files with 34 additions and 58 deletions.
26 changes: 1 addition & 25 deletions .project-words.txt
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ Actix's
alloc
Alloc
ALLOC
Amalagmates
autoplaying
autoserde
binaryen
Expand All @@ -30,54 +29,37 @@ customizability
datetime
datetimes
debian
dencode
desugared
dflt
differntly
dont
downcasting
emptively
entirele
entr
entrypoints
erro
esbuild
ESBUILD
everwhere
exmaple
favicons
fiels
filesystems
Filesystems
firefox
Flexbox
fmterr
Framesurge
geckodriver
gettting
goog
GH's
Gitter
goog
headlessly
Hola
horiztonally
incrementation
iuser
keyup
laod
leve
linux
longwinded
maintainership
maximise
minimising
modularly
mundo
oneshot
outfile
overriden
perseus
plyaground
Prefs
prerender
Prerender
Expand Down Expand Up @@ -106,20 +88,15 @@ stringifying
struct
subcrates
subfolders
synchronised
tailwindcss
takea
tempalte
templating
timeisr
tinkerings
tokio
Translationsmanager
travelled
Tribble
trybuild
TTFB
ucan
unbuilt
unergonomic
unfetched
Expand All @@ -135,5 +112,4 @@ ureq
urlencoding
verison
webapps
whcih
WORKDIR
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ Perseus uses [Bonnie](https://github.com/arctic-hen7/bonnie) for command aliasin

- `bonnie dev example showcase serve` -- serves the `showcase` example to <http://localhost:8080>

Before you do anything though, you should run `bonnie setup`, which will do few things to prepare your local development. This includes running `cargo build`, so it will takea a little while. Note that, without running this command, most other actions you try to take will cause errors.
Before you do anything though, you should run `bonnie setup`, which will do few things to prepare your local development. This includes running `cargo build`, so it will take a little while. Note that, without running this command, most other actions you try to take will cause errors.

## Testing

Expand Down
2 changes: 1 addition & 1 deletion bonnie.toml
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ check.cmd = [
]
check.desc = "checks code for formatting errors and the like"

spellcheck.cmd = "cspell lint **/*{.rs,.md}"
spellcheck.cmd = "cspell lint **/*{.rs,.md} --no-progress"
# TODO Windows version of this??
spellcheck.subcommands.store.cmd = [
"cspell --words-only --unique **/*{.rs,.md} | sort --ignore-case > .project-words.txt"
Expand Down
2 changes: 1 addition & 1 deletion docs/0.1.x/en-US/routing.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Note in the above example the usage of the `NewPost` template to override a sect

You can then match each of your routes and render it like so (subset of the previous example):

```rust,no_run,no_plyaground
```rust,no_run,no_playground
let root = web_sys::window()
.unwrap()
.document()
Expand Down
4 changes: 2 additions & 2 deletions docs/0.1.x/en-US/strategies/revalidation.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ The time based variant does have some slightly weird behavior to watch out for t

1. Evaluates your time string (e.g. `1w` for 1 week) to a number of seconds after January 1 1970 (how computers represent time). This provides a timestamp in the future, past which your page should be revalidated.
2. On every request, Perseus checks if this timestamp has been passed yet. If it has, it re-renders your page. This means that **your page will only be revalidated after the time has elapsed _and_ a user has queried it**.
3. After revalidation, Perseus repeats from step 1. However, this may not be 2 weeks after the original build (in our example of `1w`), but 1 week after the revalidation, whcih may have been later than a week after the original setting.
3. After revalidation, Perseus repeats from step 1. However, this may not be 2 weeks after the original build (in our example of `1w`), but 1 week after the revalidation, which may have been later than a week after the original setting.

To put it simply, Perseus will only revalidate when requested, so don't expect different pages to be synchronised in their revalidations, even if they all have the same timestamp.
To put it simply, Perseus will only revalidate when requested, so don't expect different pages to be synchronized in their revalidations, even if they all have the same timestamp.

This logic is a bit weird, so you may need to think about it for a bit. Don't worry though, it shouldn't impact your app negatively in any way, it's just something to take note of!

Expand Down
2 changes: 1 addition & 1 deletion docs/0.1.x/en-US/tutorials/first_app/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ You should now have an `src/` directory and a `Cargo.toml` file, which is what w
```toml
# Perseus itself, which we (amazingly) need for a Perseus app
perseus = "0.1"
# Sycamore, the library Perseus depends on for lower-leve reactivity primitivity
# Sycamore, the library Perseus depends on for lower-level reactivity primitivity
sycamore = { version = "0.5", features = ["ssr"] }
sycamore-router = "0.5"
# Serde, which lets you work with representations of data, like JSON
Expand Down
2 changes: 1 addition & 1 deletion docs/0.2.x/en-US/templates/metadata-modification.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

A big issue with only having one `index.html` file for your whole app is that you don't have the ability to define different `<title>`s and HTML metadata for each page.

However, Perseus overcomes this easily by allowing you to specify `.head()` on a `Template<G>`, which should return a closure that returns a `Template<SsrNode>` (but just write `perseus::template::HeadFn` as the return type, it's an alias for that). The `template!` you define here will be rendered to a `String` and directly interpolated into the `<head>` of any pages this template renders. If you need it to be different based on the properties, you're covered, it takes the same properties as the normal tempalte function!
However, Perseus overcomes this easily by allowing you to specify `.head()` on a `Template<G>`, which should return a closure that returns a `Template<SsrNode>` (but just write `perseus::template::HeadFn` as the return type, it's an alias for that). The `template!` you define here will be rendered to a `String` and directly interpolated into the `<head>` of any pages this template renders. If you need it to be different based on the properties, you're covered, it takes the same properties as the normal template function!

The only particular thing to note here is that, because this is rendered to a `String`, this **can't be reactive**. Variable interpolation is fine, but after it's been rendered once, the `<head>` **will not change**. If you need to update it later, you should do that with [`web_sys`](https://docs.rs/web-sys), which lets you directly access any DOM element with similar syntax to JavaScript (in fact, it's your one-stop shop for all things interfacing with the browser, as well as it's companion [`js-sys`](https://docs.rs/js-sys)).

Expand Down
4 changes: 2 additions & 2 deletions docs/0.3.0-0.3.3/en-US/hydration.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

In the examples of `Cargo.toml` files shown thus far, we've enabled a feature called `hydrate` on Perseus. This feature controls _hydration_, which is a way of making your app more performant. To explain it, we'll need to go a little in-depth.

Perseus uses server-side rendering of some kind for almost everything. In fact, unless you explicitly make something only run in the browser, Perseus will try to prerender it on the server first, either at build-time (faster, so Perseus does this for everything it can) or at request-time. This prerendering process yields a series of HTML and JSON fiels that make up the markup and state of your app. When a page is requested by a user, Perseus can serve them these files, and then the app shell (the Wasm code that runs everything in a Perseus app in the browser) will bring everything to life.
Perseus uses server-side rendering of some kind for almost everything. In fact, unless you explicitly make something only run in the browser, Perseus will try to prerender it on the server first, either at build-time (faster, so Perseus does this for everything it can) or at request-time. This prerendering process yields a series of HTML and JSON files that make up the markup and state of your app. When a page is requested by a user, Perseus can serve them these files, and then the app shell (the Wasm code that runs everything in a Perseus app in the browser) will bring everything to life.

Those prerendered files can be imagined as solid iron, but, to make your app work, we need molten iron. In the real world, you need a lot of heat to turn iron into a liquid, and you need a lot of code to turn simple markup into interactive buttons and text in a browser! So, let's go through the metaphor a bit more: the build process and server are the miners that fetch all the iron out of the mines of the tempalte code you write. Then, that iron is sent to the user's browser, and the app shell does _something_ to get molten iron that can be used to run your app.
Those prerendered files can be imagined as solid iron, but, to make your app work, we need molten iron. In the real world, you need a lot of heat to turn iron into a liquid, and you need a lot of code to turn simple markup into interactive buttons and text in a browser! So, let's go through the metaphor a bit more: the build process and server are the miners that fetch all the iron out of the mines of the template code you write. Then, that iron is sent to the user's browser, and the app shell does _something_ to get molten iron that can be used to run your app.

Without hydration, the app shell will kindly thank the server for sending it the solid iron, and will then proceed to mine more of its own. In other words, the app shell will completely ignore the prerendered files that the server has sent (displaying them only until it's ready, which is why Perseus apps still work without JavaScript!).

Expand Down
2 changes: 1 addition & 1 deletion docs/0.3.0-0.3.3/en-US/plugins/using.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,4 @@ In addition to the usual `define_app!` calls, this also uses the `plugins` param

To register a plugin, we use the `.plugin()`/`.plugin_with_client_privilege()` function on `Plugins`, which takes two parameters: the plugin's definition (a `perseus::plugins::Plugin`) and any data that should be provided to the plugin. The former should be exported from the plugin's crate, and the latter you'll need to provide based on the plugin's documentation. Note that plugins can accept almost anything as data (specifically, anything that can be expressed as `dyn Any`).

Plugins in Perseus are fantastic, but they're also a great way to increase your Wasm bundle size, which will make your website slower to laod when users first visit it. To mitigate this, Perseus lets plugin authors define where their plugins should run: in the browser (`PluginEnv::Client`), on the server-side (`PluginEnv::Server`), or on both (`PluginEnv::Both`). Plugins that only run on the server-side should be registered with `.plugin()`, and they will not be included in your final Wasm binary, which keeps your website nimble. If a plugin does need to run on the client though, it can be registered with `.plugin_with_client_privilege()` instead, which is named separately for conditional compilation reasons as well as to create a clear separation. But don't worry, if you accidentally register a plugin with the wrong function, your app won'y build, and Perseus will tell you that you've used the wrong function.
Plugins in Perseus are fantastic, but they're also a great way to increase your Wasm bundle size, which will make your website slower to load when users first visit it. To mitigate this, Perseus lets plugin authors define where their plugins should run: in the browser (`PluginEnv::Client`), on the server-side (`PluginEnv::Server`), or on both (`PluginEnv::Both`). Plugins that only run on the server-side should be registered with `.plugin()`, and they will not be included in your final Wasm binary, which keeps your website nimble. If a plugin does need to run on the client though, it can be registered with `.plugin_with_client_privilege()` instead, which is named separately for conditional compilation reasons as well as to create a clear separation. But don't worry, if you accidentally register a plugin with the wrong function, your app won'y build, and Perseus will tell you that you've used the wrong function.
2 changes: 1 addition & 1 deletion docs/0.3.4/en-US/reference/server-communication.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Here's an example of both approaches (taken from [here](https://github.com/arcti

In the above example, we fetch the server's IP address at build-time from <https://api.ipify.org> using [`ureq`](https://docs.rs/ureq), a simple (and blocking) HTTP client. Note that Perseus gives you access to a full Tokio `1.x` runtime at build time, so you can easily use a non-blocking library like [`reqwest`](https://docs.rs/reqwest), which will be faster if you're making a lot of network requests at build-time. However, for simplicity's sake, this example uses `ureq`.

One problem of fetching data at build-time though, in any framework, is that you have to fetch it again every time you rebuild your app, which slows down the build process and thus slows down your development cycle. To alleviate this, Perseus provides two helper functions, `cache_res` and `cache_fallible_res` (used for functions that return a `Result`) that can be used to wrap any asynchronous code that runs on the server-side (e.g. at build-time, request-time, etc.). The first time they run, these will just run your code, but then they'll cache the result to a file in `.perseus/`, which can be used in all subsequent requests, making your long-running code (typically network request code, but you could even put machine learning stuff in them in theory...) run almost instantaneously. Of course, sometimes you'll need to re-run that asynchronous code if you change something, which yo ucan do trivially by changing the second argument from `false` to `true`, which will override the cache and always re-run the given code.
One problem of fetching data at build-time though, in any framework, is that you have to fetch it again every time you rebuild your app, which slows down the build process and thus slows down your development cycle. To alleviate this, Perseus provides two helper functions, `cache_res` and `cache_fallible_res` (used for functions that return a `Result`) that can be used to wrap any asynchronous code that runs on the server-side (e.g. at build-time, request-time, etc.). The first time they run, these will just run your code, but then they'll cache the result to a file in `.perseus/`, which can be used in all subsequent requests, making your long-running code (typically network request code, but you could even put machine learning stuff in them in theory...) run almost instantaneously. Of course, sometimes you'll need to re-run that asynchronous code if you change something, which you can do trivially by changing the second argument from `false` to `true`, which will override the cache and always re-run the given code.

Incidentally, you can also use those functions to work in an offline environment, even if your app includes calls to external APIs at build time. As long as you've called your app's build process once so that Perseus can cache all the requests, it won't make any more network requests in development unless you tell it to explicitly or delete `.perseus/cache/`.

Expand Down
2 changes: 1 addition & 1 deletion docs/0.3.4/en-US/tutorials/second-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ Note that we also use the `#[perseus::make_rx(IndexPageStateRx)]` macro here to

### `index_page()`

This is the actual component that will render a user interface for your page. Perseus lets you provide a *template function* like this as a simple Rust function that takes in your page's state and produces a Sycamore `View<G>` (again, `G` is ambient here because of the proc macro). However, there's *a lot* of work that goes on behind the scenes to make your state reactive, register it with Perseus, manage [global state](:reference/state/global), and set up a Sycamore component that's usable by the rest of the Perseus code. This is all done with one of two attribute macros: `#[perseus::template(...)]` or `#[perseus::template_rx]`. In previous versions of Perseus, you'd use the former, which would give you an unreactive instance of your state (in our case, `IndexPageState`). However, since v0.3.4, it's recommended to use the latter, which gives you a reactive version (in our case, `IndexPageStateRx`) and can manage more advanced features of Perseus' [reactive state platform](:reference/state/rx), so that's what we use here. Also, `template_rx` manages things like Sycamore components internally for you, minimising the amount of code you actually have to write.
This is the actual component that will render a user interface for your page. Perseus lets you provide a *template function* like this as a simple Rust function that takes in your page's state and produces a Sycamore `View<G>` (again, `G` is ambient here because of the proc macro). However, there's *a lot* of work that goes on behind the scenes to make your state reactive, register it with Perseus, manage [global state](:reference/state/global), and set up a Sycamore component that's usable by the rest of the Perseus code. This is all done with one of two attribute macros: `#[perseus::template(...)]` or `#[perseus::template_rx]`. In previous versions of Perseus, you'd use the former, which would give you an unreactive instance of your state (in our case, `IndexPageState`). However, since v0.3.4, it's recommended to use the latter, which gives you a reactive version (in our case, `IndexPageStateRx`) and can manage more advanced features of Perseus' [reactive state platform](:reference/state/rx), so that's what we use here. Also, `template_rx` manages things like Sycamore components internally for you, minimizing the amount of code you actually have to write.

Note that `index_page()` takes `IndexPageStateRx` as an argument, which it can then access in the `view!`. This is Sycamore's interpolation system, which you can read about [here](https://sycamore-rs.netlify.app/docs/basics/template), but all you need to know is that it's basically seamless and works exactly as you'd expect (remember though that, because we're using the `template_rx` macro, we have to use a reactive state `struct`, which we generate with the `make_rx` macro, so all our fields are wrapped in `Signal`s, which is why we use `.get()`).

Expand Down
2 changes: 1 addition & 1 deletion examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This folder contains all the examples for Perseus! These are divided into three categories: core examples, which demonstrate core features of Perseus and are used as end-to-end tests; demonstrative examples, which quickly demonstrate how to do certain things with Perseus; and comprehensive examples, which show off whole systems built with Perseus.

There's also a `.base/` folder that contains a template that new examples should be built from. If you'd like to create a new exmaple, you should copy this directory and modify it to your needs, placing your new example in the appropriate category (this will usually be `demos` or `comprehensive`, you should only put it in `core` if you've confirmed this with a maintainer or if you've built the feature it shows off).
There's also a `.base/` folder that contains a template that new examples should be built from. If you'd like to create a new example, you should copy this directory and modify it to your needs, placing your new example in the appropriate category (this will usually be `demos` or `comprehensive`, you should only put it in `core` if you've confirmed this with a maintainer or if you've built the feature it shows off).

Each of the examples here are fully self-contained Perseus apps, though they use relative path dependencies to the bleeding edge versions of the Perseus packages in this repository. They're also designed to be used with the local, bleeding-edge version of the CLI, which can be invoked by running `bonnie dev example <category> <example> <cli-command>`, where `<cli-command>` is any series of arguments you'd provide to the usual Perseus CLI.

Expand Down
2 changes: 1 addition & 1 deletion examples/core/index_view/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ pub fn main<G: Html>() -> PerseusApp<G> {
.error_pages(crate::error_pages::get_error_pages)
.index_view(|cx| {
sycamore::view! { cx,
// We don't need a `<!DOCTYPE html>`, that's added automatically by Perseus (though that can be overriden if you really want by using `.index_view_str()`)
// We don't need a `<!DOCTYPE html>`, that's added automatically by Perseus (though that can be overridden if you really want by using `.index_view_str()`)
// We need a `<head>` and a `<body>` at the absolute minimum for Perseus to work properly (otherwise certain script injections will fail)
head {
title { "Perseus Index View Example" }
Expand Down
Loading

0 comments on commit e678d44

Please sign in to comment.