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::prelude::*;
use sycamore::prelude::*;

#[perseus::main(perseus_axum::dflt_server)]
pub fn main<G: Html>() -> PerseusApp<G> {
    PerseusApp::new()
        .template(
            Template::build("index")
                .view(|cx| {
                    view! { cx,
                        p { "Hello World!" }
                    }
                })
                .build()
        )
}

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

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.

Perseus wouldn’t be posible without the hard work of all these wonderful people!

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

Modules

  • client
    Utilities for initializing the Perseus client.
  • 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_views
    Utilities surrounding ErrorViews and their management.
  • errors
  • i18n
    Utilities for internationalization, the process of making your app available in multiple languages.
  • internal
    Internal utilities for lower-level work.
  • path
    Utilities for working with typed paths.
  • plugins
    Utilities for working with plugins.
  • prelude
    A series of imports needed by most Perseus apps, in some form. This should be used in conjunction with the Sycamore prelude.
  • reactor
    The core of the Perseus browser-side system. This is used on the engine-side as well for rendering.
  • 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 stores::ImmutableStore and stores::MutableStore for details.
  • template
    Utilities for working with templates and state generation. This is by far the module you’ll probably access the most.
  • turbine
    The core of the Perseus state generation system. The internals of Perseus’ state generation platform. This is not responsible for the reactivity of state, or any other browser-side work. This is responsible for the actual generation of state on the engine-side, at both build-time and request-time.
  • utils
    General utilities that may be useful while building Perseus apps.

Macros

  • 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

Type Definitions

  • PerseusNodeType
    An alias for DomNode, HydrateNode, or SsrNode, depending on the hydrate feature flag and compilation target.
  • Request
    All HTTP requests use empty bodies for simplicity of passing them around. They’ll never need payloads (value in path requested).

Attribute Macros

  • auto_scope
    A helper macro for templates that use reactive state. Once, this was needed on all Perseus templates, however, today, templates that take no state, or templates that take unreactive state, can be provided as normal functions to the methods .view() and .view_with_unreactive_state() respectively, on Perseus’ Template type.
  • 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.
  • browser_only_fn
    A convenience macro that makes sure the given function is only defined on the browser-side, creating an empty function on the engine-side. Perseus implicitly expects your browser-side state modification functions to be defined in this way (though you certainly don’t have to use this macro).
  • 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.
  • engine_only_fn
    A convenience macro that makes sure the given function is only defined on the engine-side, creating an empty function on the browser-side. Perseus implicitly expects most of your state generation functions to be defined in this way (though you certainly don’t have to use this macro).
  • 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.
  • 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<>.

Derive Macros

  • ReactiveState
    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.
  • UnreactiveState