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)
Usage
Here’s a taste of Perseus (see the tiny example for more):
use perseus::{Html, PerseusApp, Template};
use sycamore::view;
#[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!
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 Fluenthydrate– 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
The remaining features are used internally by the other Perseus packages, and enabling them manually in your project will very likely wreak havoc unless you seriously know what you’re doing!
tinker-plugins– makes tinker plugins be registeredserver-side– enables various functions only used on the server-side (minimizes the client-side bundle)standalone– makes Perseus able to be run as a standalone binary by changing some minor internal defaults
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
Modules
Utilities for building an app.
A series of exports that should be unnecessary for nearly all uses of Perseus. These are used principally in developing alternative engines.
Utilities for working with plugins.
Utilities for working with Perseus’ state platform.
Utilities for working with immutable and mutable stores. You can learn more about these in the book.
Utilities for developing templates, particularly including return types for various rendering strategies.
Macros
Creates a new GenericErrorWithCause efficiently. This allows you to explicitly return errors from anything that returns
RenderFnResultWithCause, which includes 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>):
Defines the components to create an entrypoint for the app. The actual entrypoint is created in the .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.
Gets the RenderCtx efficiently.
Gets a HashMap of the given templates by their paths for serving. This should be manually wrapped for the pages your app provides
for convenience.
Gets a HashMap of the given templates by their paths for serving. This should be manually wrapped for the pages your app provides
for convenience.
Checks if we’re on the server or the client. This must be run inside a reactive scope (e.g. a template! or create_effect),
because it uses Sycamore context.
Gets the link to the given resource in internationalized form conveniently.
Translates the given ID conveniently, taking arguments for interpolation as required.
A simple macro for listening for a checkpoint in a test.
Logs the given format!-style data to the browser’s console, or to stdout on the server.
Structs
Rendering backend for the DOM.
A type alias for the HashMap the user should provide for error pages.
Represents an HTTP request.
Rendering backend for the DOM with hydration support.
Represents the data necessary to render a page, including document metadata.
The options for constructing a Perseus app. These encompass all the information Perseus needs to know to create your app. Every Perseus app using the engine must export one of these.
A Perseus plugin. This must be exported by all plugin crates so the user can register the plugin easily.
A representation of all the plugins used by an app. Due to the sheer number and compexity of nested fields, this is best transferred
in an Rc, which unfortunately results in double indirection for runner functions.
Rendering backend for Server Side Rendering, aka. SSR.
Represents all the different states that can be generated for a single template, allowing amalgamation logic to be run with the knowledge of what did what (rather than blindly working on a vector).
This allows the specification of all the template templates in an app and how to render them. If no rendering logic is provided at all,
the template will be prerendered at build-time with no state. All closures are stored on the heap to avoid hellish lifetime specification.
All properties for templates are passed around as strings to avoid type maps and other horrible things, this only adds one extra
deserialization call at build time. This only actually owns a two Strings and a bool.
Traits
Trait that is implemented by all [GenericNode] backends that render to HTML.
A trait for the interface for a plugin action, which abstracts whether it’s a functional or a control action.
Trait that is implemented for enums that can match routes.
Functions
The component that represents the entrypoint at which Perseus will inject itself. You can use this with the .index_view() method of PerseusApp to avoid having to create the entrypoint
<div> manually.
Same as cache_res, but takes a function that returns a Result, allowing you to use ? and the like inside your logic.
Runs the given function once and then caches the result to the filesystem for future execution. Think of this as filesystem-level memoizing. In future, this will be broken out into its own crate and wrapped by Perseus. The second parameter to this allows forcing the function to re-fetch data every time, which is useful if you want to revalidate data or test your fetching logic again. Note that a change to the logic will not trigger a reload unless you make it do so. For this reason, it’s recommended to only use this wrapper once you’ve tested your fetching logic.
Navigates to the specified url. The url should have the same origin as the app.
Navigates to the specified 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.
Spawns a !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
A type alias for the function that modifies the document head. This is just a template function that will always be server-side rendered in function (it may be rendered on the client, but it will always be used to create an HTML string, rather than a reactive template).
An alias for the usual kind of Perseus app, which uses the filesystem-based mutable store and translations manager.
An alias for a Perseus app that uses a custom mutable store type.
An alias for a fully customizable Perseus app that can accept a custom mutable store and a custom translations manager. Alternatively, you could just use PerseusAppBase directly.
An alias for a Perseus app that uses a custom translations manager type.
A generic error type that can be adapted for any errors the user may want to return from a render function. .into() can be used
to convert most error types into this without further hassle. Otherwise, use Box::new() on the type.
A generic error type that can be adapted for any errors the user may want to return from a render function, as with 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.
All HTTP requests use empty bodies for simplicity of passing them around. They’ll never need payloads (value in path requested).
Attribute Macros
Annotates functions used for amalgamating build-time and request-time states to support automatic serialization/deserialization of app state and
client/server division. This supersedes the old autoserde macro for state amalgamation functions.
Marks the annotated code as only to be run in the browser. This is the opposite of (and mutually exclusive with) #[engine]. This
resolves to a target-gate that makes the annotated code run only on targets that are wasm32.
Marks the given function as the browser entrypoint into your app. This is designed for more complex apps that need to manually distinguish between the engine and browser entrypoints.
Annotates functions used for generating paths at build time to support automatic serialization/deserialization of app state and
client/server division. This supersedes the old autoserde macro for build paths functions.
Annotates functions used for generating state at build time to support automatic serialization/deserialization of app state and
client/server division. This supersedes the old autoserde macro for build state functions.
Marks the annotated code as only to be run as part of the engine (the server, the builder, the exporter, etc.). This resolves to a
target-gate that makes the annotated code run only on targets that are not wasm32.
Marks the given function as the engine entrypoint into your app. This is designed for more complex apps that need to manually distinguish between the engine and browser entrypoints.
Annotates functions used for generating global state at build time to support automatic serialization/deserialization of app state and
client/server division. This supersedes the old autoserde macro for global build state functions.
Labels a function as a Perseus head function, which is very similar to a template, but
for the HTML metadata in the document <head>.
Marks the given function as the universal entrypoint into your app. This is designed for simple use-cases, and the annotated function should return
a PerseusApp. This will expand into separate main() functions for both the browser and engine sides.
This is identical to #[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.
Processes the given 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.
Annotates functions used for generating state at request time to support automatic serialization/deserialization of app state and
client/server division. This supersedes the old autoserde macro for request state functions.
Annotates functions used for generating state at build time to support automatic serialization/deserialization of app state and
client/server division. This supersedes the old autoserde macro for build state functions.
Annotates functions used for checking if a template should revalidate and request-time states to support automatic serialization/deserialization
of app state and client/server division. This supersedes the old autoserde macro for revalidation determination functions.
Labels a Sycamore component as a Perseus template, turning it into something that can be easily inserted into the .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>).
The new version of #[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.
Marks the given function as a Perseus test. Functions marked with this attribute must have the following signature:
async fn foo(client: &mut fantoccini::Client) -> Result<>.
Derive Macros
The Route procedural macro.