Crate perseus

source · [−]
Expand description

Perseus

Book API Docs Crate Page Top Language Discord Chat

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::{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!

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.6
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 Fluent
  • macros (default) — adds support for macros that will make your life much easier
  • dflt_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-side
  • hydrate — 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 app
  • hsr (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

engine

Utilities for working with the engine-side, particularly with regards to setting up the entrypoint for your app’s build/export/server processes.

error_pages

Utilities surrounding ErrorPages and their management.

errors
i18n

Utilities for internationalization, the process of making your app available in multiple languages.

internal

TODO

plugins

Utilities for working with plugins.

router

Utilities for working with the router. Note that you should only have to use these when waiting for a page transition in normal use-cases.

server

Utilities for working with the server. These are fairly low-level, and are intended for use by those developing new server integrations. This module contains the necessary primitives to run Perseus as a server, regardless of framework. This module aims to provide as many abstractions as possible to minimize work when maintaining multiple server-framework integrations. Apart from building your own integrations, you should never need to use this module (though some plugins may need types in here).

state

Utilities for working with Perseus’ state platform.

stores

Utilities for working with immutable and mutable stores. See [ImmutableStore] and [MutableStore] for details.

template

Utilities for working with templates and state generation. This is by far the module you’ll procably access the most.

utils

General utilities that may be useful while building Perseus apps.

Macros

blame_err

Creates a new [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>):

define_app

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.

get_render_ctx

Gets the RenderCtx efficiently.

get_templates_map

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.

get_templates_map_atomic

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.

is_serverDeprecated

Checks if we’re on the server or the client. This must be run inside a reactive scope (e.g. a view! or create_effect), because it uses Sycamore context.

link

Gets the link to the given resource in internationalized form conveniently. The final argument to any call of this macro must be a Sycamore reactive scope provided to the relevant Perseus template.

t

Translates the given ID conveniently, taking arguments for interpolation as required. The final argument to any call of this macro must be a Sycamore reactive scope provided to the relevant Perseus template.

wait_for_checkpoint

A simple macro for listening for a checkpoint in a test.

web_log

Logs the given format!-style data to the browser’s console, or to stdout on the server.

Structs

DomNode

Rendering backend for the DOM.

HttpRequest

Represents an HTTP request.

HydrateNode

Rendering backend for the DOM with hydration support.

PerseusAppBase

The options for constructing a Perseus app. This struct will tie together all your code, declaring to Perseus where your templates, error pages, static content, etc. are.

SsrNode

Rendering backend for Server Side Rendering, aka. SSR.

Template

A single template in an app. Each template is comprised of a Sycamore view, a state type, and some functions involved with generating that state. Pages can then be generated from particular states. For instance, a single docs template could have a state struct that stores a title and some content, which could then render as many pages as desired.

Traits

Html

Trait that is implemented by all [GenericNode] backends that render to HTML.

Functions

PerseusRoot

The component that represents the entrypoint at which Perseus will inject itself. You can use this with the .index_view() method of PerseusAppBase to avoid having to create the entrypoint <div> manually.

navigate

Navigates to the specified url. The url should have the same origin as the app.

navigate_replace

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.

spawn_local_scoped

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

PerseusApp

An alias for the usual kind of Perseus app, which uses the filesystem-based mutable store and translations manager. See PerseusAppBase for details.

PerseusAppWithMutableStore

An alias for a Perseus app that uses a custom mutable store type. See PerseusAppBase for details.

PerseusAppWithMutableStoreAndTranslationsManager

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.

PerseusAppWithTranslationsManager

An alias for a Perseus app that uses a custom translations manager type. See PerseusAppBase for details.

RenderFnResult

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.

RenderFnResultWithCause

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.

Request

All HTTP requests use empty bodies for simplicity of passing them around. They’ll never need payloads (value in path requested).

Attribute Macros

amalgamate_states

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.

browser

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.

browser_main

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.

build_paths

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.

build_state

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.

engine

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.

engine_main

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.

global_build_state

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.

head

Labels a function as a Perseus head function, which is very similar to a template, but for the HTML metadata in the document <head>.

main

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.

main_export

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.

make_rx

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.

request_state

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.

set_headers

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.

should_revalidate

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.

template

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>).

template_rx

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.

test

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<>.