Crate perseus[−][src]
Expand description
Perseus is a blazingly fast frontend web development framework built in Rust with support for major rendering strategies, reactivity without a virtual DOM, and extreme customizability. It wraps the lower-level capabilities of Sycamore and provides a NextJS-like API!
- ✨ 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, mostly)
- ✨ CLI harness that lets you build apps with ease and confidence
This is the documentation for the core Perseus crate, but there’s also a CLI and integrations to make serving apps easier!
Resources
These docs will help you as a reference, but the book should be your first port of call for learning about how to use Perseus and how it works.
- The Book
- GitHub repository
- Crate page
- Gitter chat
- Discord server channel (for Sycamore-related stuff)
Features
Perseus performs internationalization using translators, each of which utilizes some translation engine, like Fluent.
Each of the available translations are feature-gated, and can be enabled with the translator-[engine-name] feature. You can set
the default translator by setting the translator-dflt-[engine-name] (you of course can’t have more than one default translator).
You can read more about this system here.
Re-exports
Modules
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 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 an app-specific routing struct. Sycamore expects an enum to do this, so we create a struct that behaves similarly. If
we don’t do this, we can’t get the information necessary for routing into the enum at all (context and global variables don’t suit
this particular case).
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 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.
Structs
Rendering backend for the DOM.
A type alias for the HashMap the user should provide for error pages.
Represents an HTTP request.
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
Abstraction over a rendering backend.
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
Marks a checkpoint in the code and alerts any tests that it’s been reached by creating an element that represents it. The preferred
solution would be emitting a DOM event, but the WebDriver specification currently doesn’t support waiting on those (go figure). This
will only create a custom element if the __PERSEUS_TESTING JS global variable is set to true.
Navigates to the specified url. The url should have the same origin as the app.
Type Definitions
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
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.