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

pub use http;

pub use crate::build::build_app;

pub use crate::build::build_template;

pub use crate::build::build_templates_for_locale;

pub use crate::error_pages::ErrorPages;

pub use crate::errors::err_to_status_code;

pub use crate::errors::ErrorCause;

pub use crate::errors::GenericErrorWithCause;

pub use crate::export::export_app;

pub use crate::serve::get_page;

pub use crate::serve::get_render_cfg;

pub use crate::shell::app_shell;

pub use crate::template::RenderFnResult;

pub use crate::template::RenderFnResultWithCause;

pub use crate::template::States;

pub use crate::template::Template;

pub use crate::template::TemplateMap;

pub use crate::translations_manager::FsTranslationsManager;

pub use crate::translations_manager::TranslationsManager;

Modules

build

Utilities for building your app.

error_pages

Utilities regarding the formation of error pages for HTTP status codes, like a 404 Not Found page.

errors

export

Utilities to do with exporting your app to purely static files.

html_shell

Utilities for manipulating the HTML shell. These are primarily used in exporting and serving.

path_prefix

Utilities relating to working with path prefixes for when a site is hosted at a relative path.

plugins

Utilities for managing and creating plugins.

router

Utilities regarding routing.

serve

Utilities for serving your app. These are platform-agnostic, and you probably want an integration like perseus-actix-web.

shell

Utilities to do with the app shell. You probably don’t want to delve into here.

stores

Utilities for mutable/immutable store managers. See the book for more details on this.

template

Utilities to do with templating. This is where the bulk of designing apps lies.

translations_manager

Utilities for creating custom translations managers, as well as the default FsTranslationsManager.

translator

Utilities regarding translators, including the default FluentTranslator.

Macros

create_app_route

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

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

is_server

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.

link

Gets the link to the given resource in internationalized form conveniently.

t

Translates the given ID conveniently, taking arguments for interpolation as required.

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.

Structs

ClientTranslationsManager

Manages translations in the app shell. This handles fetching translations from the server as well as caching for performance. This is distinct from TranslationsManager in that it operates on the client-side rather than on the server. This optimizes for users viewing many pages in the same locale, which is by far the most common use of most websites in terms of i18n.

DomNode

Rendering backend for the DOM.

HttpRequest

Represents an HTTP request.

Locales

Defines app information about i18n, specifically about which locales are supported.

SsrNode

Rendering backend for Server Side Rendering, aka. SSR.

Translator

Manages translations on the client-side for a single locale using Mozilla’s Fluent syntax. This should generally be placed into an Rc<T> and referred to by every template in an app. You do NOT want to be cloning potentially thousands of translations!

Constants

TRANSLATOR_FILE_EXT

The file extension used by the Fluent translator, which expects FTL files.

Traits

GenericNode

Abstraction over a rendering backend.

Route

Trait that is implemented for enums that can match routes.

Functions

detect_locale

Detects which locale the user should be served and redirects appropriately. This should only be used when the user navigates to a page like /about, without a locale. This will only work on the client-side (needs access to browser i18n settings). Any pages that direct to this should be explicitly excluded from search engines (they don’t show anything until redirected). This is guided by RFC 4647, but is not yet fully compliant (only supports xx-XX form locales). Note that this bypasses Sycamore’s routing logic and triggers a full reload.

navigate

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