Expand description
Perseus
Perseus is a blazingly fast frontend web development framework built in Rust with support for generating page state at build-time, request-time, incrementally, or whatever you’d like! It supports reactivity using Sycamore, and builds on it to provide a fully-fledged framework for developing modern apps.
- 📕 Supports static generation (serving only static resources)
- 🗼 Supports server-side rendering (serving dynamic resources)
- 🔧 Supports revalidation after time and/or with custom logic (updating rendered pages)
- 🛠️ Supports incremental regeneration (build on demand)
- 🏭 Open build matrix (use any rendering strategy with anything else)
- 🖥️ CLI harness that lets you build apps with ease and confidence
- 🌐 Full i18n support out-of-the-box with Fluent
- 🏎 Lighthouse scores of 100 on desktop and over 95 on mobile
- ⚡ Support for hot state reloading (reload your entire app’s state after you make any code changes in development, Perseus is the only framework in the world that can do this, to our knowledge)
What’s it like?
Here’s a taste of Perseus (see the tiny example for more):
use perseus::prelude::*;
use sycamore::prelude::*;
#[perseus::main(perseus_warp::dflt_server)]
pub fn main<G: Html>() -> PerseusApp<G> {
PerseusApp::new().template(|| {
Template::new("index").template(|cx, _| {
view! { cx,
p { "Hello World!" }
}
})
})
}
Check out the book to learn how to turn that into your next app!
Quick start
If you want to start working with Perseus right away, run the following commands and you’ll have a basic app ready in no time! (Or, more accurately, after Cargo compiles everything…)
cargo install perseus-cli --version 0.4.0-beta.11
perseus new my-app
cd my-app/
perseus serve -w
Then, hop over to http://localhost:8080 and see a placeholder app, in all its glory! If you change some code, that’ll automatically update, reloading the browser all by itself. (This rebuilding might take a while though, see here for how to speed things up.)
Check out our getting started tutorial for more, or head over to out core principles page, which explains the basics of how Perseus works. Enjoy!
Aim
Support every major rendering strategy and provide developers the ability to efficiently create super-fast apps with Rust and a fantastic developer experience!
Motivation
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. But why stop there?
Contributing
We appreciate all kinds of contributions, check out our contributing guidelines for more information! Also, please be sure to follow our code of conduct.
You can also chat about Perseus on our channel on Sycamore’s Discord server.
License
See LICENSE
.
Features
translator-fluent
— enables internationalization using Fluentmacros
(default) — adds support for macros that will make your life much easierdflt_engine
(default) — adds support for the default engine-side mechanics (you would only not want this in extremely niche use-cases)client_helpers
(default) — adds useful helpers for managing the browser-sidehydrate
— enables Sycamore’s experimental hydration system (if you experience odd issues, try disabling this)preload-wasm-on-redirect
— experimentally preloads the Wasm bundle for locale redirections (this only partially works right now)idb-freezing
— enables utilities for freezing your app’s state to IndexedDB in the browser (see the book)live-reload
(default) — enables reloading the browser automatically when you make changes to your apphsr
(default) — enables hot state reloading, which reloads the state of your app right before you made code changes in development, allowing you to pick up where you left off
Packages
This is the API documentation for the core perseus
package, which underlies all Perseus apps. Note that Perseus mostly uses the book for
documentation, and this should mostly be used as a secondary reference source. You can also find full usage examples here.
Re-exports
pub use http;
pub use crate::error_pages::ErrorPages;
pub use crate::errors::ErrorCause;
pub use crate::errors::GenericErrorWithCause;
Modules
ErrorPages
and their management.ImmutableStore
] and [MutableStore
] for details.Macros
GenericErrorWithCause
(the error type behind
RenderFnResultWithCause
) efficiently.
This allows you to explicitly return errors from any state-generation
functions, including both an error and a statement of whether the server or
the client is responsible. With this macro, you can use any of the following
syntaxes (substituting "error!"
for any error that can be converted with
.into()
into a Box<dyn std::error::Error>
):.perseus/
crate (where we can get all the
dependencies without driving the user’s Cargo.toml
nuts). This also
defines the template map. This is intended to make compatibility with the
Perseus CLI significantly easier.RenderCtx
efficiently.HashMap
of the given templates by their paths for serving. This
should be manually wrapped for the pages your app provides for convenience.HashMap
of the given templates by their paths for serving. This
should be manually wrapped for the pages your app provides for convenience.view!
or create_effect
), because it uses
Sycamore context.format!
-style data to the browser’s console, or to stdout
on the server.Structs
struct
will tie
together all your code, declaring to Perseus where your templates,
error pages, static content, etc. are.docs
template could have a state struct
that stores a title and some content,
which could then render as many pages as desired.Traits
GenericNode
] backends that render to HTML.Functions
.index_view()
method of
PerseusAppBase
to avoid having to create the entrypoint <div>
manually.url
. The url should have the same origin as the app.url
without adding a new history entry. Instead, this replaces the
current location with the new url
. The url should have the same origin as the app.!Send
future on the current scope. If the scope is destroyed before the future is
completed, it is aborted immediately. This ensures that it is impossible to access any
values referencing the scope after they are destroyed.Type Definitions
PerseusAppBase
for details.PerseusAppBase
for details.PerseusAppBase
directly.PerseusAppBase
for details..into()
can be used to convert most error
types into this without further hassle. Otherwise, use Box::new()
on the
type.RenderFnResult<T>
. However, this
also includes a mandatory statement of causation for any errors, which
assigns blame for them to either the client or the server. In cases where
this is ambiguous, this allows returning accurate HTTP status codes.Attribute Macros
autoserde
macro for state
amalgamation functions.#[engine]
. This resolves to a
target-gate that makes the annotated code run only on targets that are
wasm32
.autoserde
macro for build paths
functions.autoserde
macro for build state
functions.wasm32
.autoserde
macro for global
build state functions.<head>
.PerseusApp
. This will expand into separate main()
functions for both
the browser and engine sides.#[main]
, except it doesn’t require a server
integration, because it sets your app up for exporting only. This is useful
for apps not using server-requiring features (like incremental static
generation and revalidation) that want to avoid bringing in another
dependency on the server-side.struct
to create a reactive version by wrapping each
field in a Signal
. This will generate a new struct
with the given name
and implement a .make_rx()
method on the original that allows turning an
instance of the unreactive struct
into an instance of the reactive one.autoserde
macro for request state
functions.autoserde
macro for build state
functions.autoserde
macro for revalidation determination functions..template()
function, avoiding the
need for you to manually serialize/deserialize things. This should be
provided the name of the Sycamore component (same as given to Sycamore’s
#[component()]
, but without the <G>
).#[template]
designed for reactive state. This can
interface automatically with global state, and will automatically provide
Sycamore #[component]
annotations. To use this, you don’t need to provide
anything other than an optional custom type parameter letter (by default,
G
will be used). Unlike with the original macro, this will automatically
handle component names internally.async fn foo(client: &mut fantoccini::Client) -> Result<>
.