Struct perseus::prelude::PerseusAppBase

pub struct PerseusAppBase<G: Html, M: MutableStore, T: TranslationsManager> { /* private fields */ }

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.

Memory leaks

This struct internally stores all templates and capsules as static references, since they will definitionally be required for the lifetime of the app, and since this enables support for capsules created and managed through a lazy_static!, a very convenient and efficient pattern.

However, this does mean that the methods on this struct for adding templates and capsules perform Box::leak calls internally, creating deliberate memory leaks. This would be …

Implementations

impl<G: Html, T: TranslationsManager> PerseusAppBase<G, FsMutableStore, T>

pub fn new() -> Self

Creates a new instance of a Perseus app using the default filesystem-based mutable store (see FsMutableStore). For most apps, this will be sufficient. Note that this initializes the translations manager as a dummy (see FsTranslationsManager), and adds no templates or error pages.

In development, you can get away with defining no error pages, but production apps (e.g. those created with perseus deploy) MUST set their own custom error pages.

This is asynchronous because it creates a translations manager in the background.

pub fn new() -> Self

Creates a new instance of a Perseus app using the default filesystem-based mutable store (see FsMutableStore). For most apps, this will be sufficient. Note that this initializes the translations manager as a dummy (see FsTranslationsManager), and adds no templates or error pages.

In development, you can get away with defining no error pages, but production apps (e.g. those created with perseus deploy) MUST set their own custom error pages.

This is asynchronous because it creates a translations manager in the background.

impl<G: Html, M: MutableStore> PerseusAppBase<G, M, FsTranslationsManager>

pub fn locales_lit_and_translations_manager(self, locales: Locales) -> Self

The same as .locales_and_translations_manager(), but this accepts a literal Locales struct, which means this can be used when you’re using FsTranslationsManager but when you don’t know if your app is using i18n or not (almost always middleware).

pub fn locales_and_translations_manager( self, default: &str, other: &[&str] ) -> Self

Sets the internationalization information for an app using the default translations manager (FsTranslationsManager). This handles locale caching and the like automatically for you, though you could alternatively use .locales() and .translations_manager() independently to customize various behaviors. This takes the same arguments as .locales(), so the first argument is the default locale (used as a fallback for users with no locale preferences set in their browsers), and the second is a list of other locales supported.

If you’re not using i18n, you don’t need to call this function. If you for some reason do have to though (e.g. overriding some other preferences in middleware), use .disable_i18n(), not this, as you’re very likely to shoot yourself in the foot! (If i18n is disabled, the default locale MUST be set to xx-XX, for example.)

impl<G: Html, M: MutableStore, T: TranslationsManager> PerseusAppBase<G, M, T>

pub fn new_with_mutable_store(mutable_store: M) -> Self

Creates a new instance of a Perseus app, with the default options and a customizable MutableStore, using the default dummy FsTranslationsManager by default (though this can be changed).

pub fn root(self, val: &str) -> Self

Sets the HTML ID of the <div> element at which to insert Perseus. In your index view, this should use PerseusRoot.

Note: if you’re using string HTML, the <div> with this ID MUST look exactly like this: <div id="some-id-here"></div>, spacing and all!

pub fn static_dir(self, val: &str) -> Self

Sets the location of the directory storing static assets to be hosted under the URL /.perseus/static/. By default, this is static/ at the root of your project.

pub fn templates(self, val: Vec<Template<G>>) -> Self

Sets all the app’s templates. This takes a vector of templates.

Usually, it’s preferred to run .template() once for each template, rather than manually constructing this more inconvenient type.

pub fn template(self, val: impl Into<Forever<Template<G>>>) -> Self

Adds a single new template to the app. This expects the output of a function that is generic over G: Html. If you have something with a predetermined type, like a lazy_static! that’s using PerseusNodeType, you should use .template_ref() instead. For more information on the differences between the function and referrence patterns, see the book.

See Template for further details.

pub fn template_ref<H: Html>(self, val: impl Into<Forever<Template<H>>>) -> Self

Adds a single new template to the app. This can accept either an owned Template or a static reference to one, as might be created by a lazy_static!. The latter would force you to specify the rendering backend type (G) manually, using a smart alias like PerseusNodeType. This method performs internal type coercions to make statics work neatly.

If your templates come from functions like get_template, that are generic over G: Html, you can use .template(), to avoid having to specify ::<G> manually.

See Template for further details, and the book for further details on the differences between the function and reference patterns.

pub fn capsule<P: Clone + 'static>( self, val: impl Into<Forever<Capsule<G, P>>> ) -> Self

Adds a single new capsule to the app. Like .template(), this expects the output of a function that is generic over G: Html. If you have something with a predetermined type, like a lazy_static! that’s using PerseusNodeType, you should use .capsule_ref() instead. For more information on the differences between the function and reference patterns, see the book.

See Capsule for further details.

pub fn capsule_ref<H: Html, P: Clone + 'static>( self, val: impl Into<Forever<Capsule<H, P>>> ) -> Self

Adds a single new capsule to the app. This behaves like .template_ref(), but for capsules.

See Capsule for further details.

pub fn error_views(self, val: ErrorViews<G>) -> Self

Sets the app’s error views. See ErrorViews for further details.

pub fn global_state_creator(self, val: GlobalStateCreator) -> Self

Sets the app’s GlobalStateCreator.

pub fn locales(self, default: &str, other: &[&str]) -> Self

Sets the locales information for the app. The first argument is the default locale (used as a fallback for users with no locale preferences set in their browsers), and the second is a list of other locales supported.

Note that this does not update the translations manager, which must be done separately (if you’re using FsTranslationsManager, the default, you can use .locales_and_translations_manager() to set both at once).

If you’re not using i18n, you don’t need to call this function. If you for some reason do have to though (e.g. overriding some other preferences in middleware), use .disable_i18n(), not this, as you’re very likely to shoot yourself in the foot! (If i18n is disabled, the default locale MUST be set to xx-XX, for example.)

pub fn locales_lit(self, val: Locales) -> Self

Sets the locales information directly based on an instance of Locales. Usually, end users will use .locales() instead for a friendlier interface.

pub fn translations_manager( self, val: impl Future<Output = T> + 'static ) -> Self

Sets the translations manager. If you’re using the default translations manager (FsTranslationsManager), you can use .locales_and_translations_manager() to set this automatically based on the locales information. This takes a Future<Output = T>, where T is your translations manager’s type.

The reason that this takes a Future is to avoid the use of .await in your app definition code, which must be synchronous due to constraints of Perseus’ browser-side systems. When your code is run on the server, the Future will be .awaited on, but in Wasm, it will be discarded and ignored, since the translations manager isn’t needed in Wasm.

This is generally intended for use with custom translations manager or specific use-cases with the default (mostly to do with custom caching behavior).

pub fn disable_i18n(self) -> Self

Explicitly disables internationalization. You shouldn’t ever need to call this, as it’s the default, but you may want to if you’re writing middleware that doesn’t support i18n.

pub fn static_aliases(self, val: HashMap<String, String>) -> Self

Sets all the app’s static aliases. This takes a map of URLs (e.g. /file) to resource paths, relative to the project directory (e.g. style.css). Generally, calling .static_alias() many times is preferred.

pub fn static_alias(self, url: &str, resource: &str) -> Self

Adds a single static alias. This takes a URL path (e.g. /file) followed by a path to a resource (which must be within the project directory, e.g. style.css).

pub fn plugins(self, val: Plugins) -> Self

Sets the plugins that the app will use. See Plugins for further details.

pub fn mutable_store(self, val: M) -> Self

Sets the MutableStore for the app to use, which you would change for some production server environments if you wanted to store build artifacts that can change at runtime in a place other than on the filesystem (created for serverless functions specifically).

pub fn immutable_store(self, val: ImmutableStore) -> Self

Sets the ImmutableStore for the app to use. You should almost never need to change this unless you’re not working with the CLI.

pub fn index_view_str(self, val: &str) -> Self

Sets the index view as a string. This should be used if you’re using an index.html file or the like.

Note: if possible, you should switch to using .index_view(), which uses a Sycamore view rather than an HTML string.

pub fn index_view<'a>(self, f: impl Fn(Scope<'_>) -> View<SsrNode> + 'a) -> Self

Sets the index view using a Sycamore view, which avoids the need to write any HTML by hand whatsoever. Note that this must contain a <head> and <body> at a minimum.

Warning: this view can’t be reactive (yet). It will be rendered to a static string, which won’t be hydrated.

pub fn pss_max_size(self, val: usize) -> Self

Sets the maximum number of pages that can have their states stored in the page state store before the oldest will be evicted. If your app is taking up a substantial amount of memory in the browser because your page states are fairly large, making this smaller may help.

By default, this is set to 25. Higher values may lead to memory difficulties in both development and production, and the poor user experience of a browser that’s substantially slowed down.

WARNING: any setting applied here will impact HSR in development! (E.g. setting this to 1 would mean your position would only be saved for the most recent page.)

pub fn panic_handler( self, val: impl Fn(&PanicInfo<'_>) + Send + Sync + 'static ) -> Self

Sets the browser-side panic handler for your app. This is a function that will be executed if your app panics (which should never be caused by Perseus unless something is seriously wrong, it’s much more likely to come from your code, or third-party code).

In the case of a panic, Perseus will automatically try to render a full popup error to explain the situation to the user before terminating, but, since it’s impossible to use the plugins in the case of a panic, this function is provided as an alternative in case you want to perform other work, like sending a crash report.

This function must not panic itself, because Perseus renders the message after your handler is executed. If it panics, that popup will never get to the user, leading to very poor UX. That said, don’t stress about calling things like web_sys::window().unwrap(), because, if that fails, then trying to render a popup will definitely fail anyway. Perseus will attempt to write an error message to the console before this, just in case anything panics.

Note that there is no access within this function to Sycamore, page state, global state, or translators. Assume that your code has completely imploded when you write this function. Anything more advanced should be left to your error views system, when it handles ClientError::Panic.

This has no default value.

pub fn get_root(&self) -> Result<String, PluginError>

Gets the HTML ID of the <div> at which to insert Perseus.

pub fn get_index_view_str(&self) -> String

Gets the index view as a string, without generating an HTML shell (pass this into ::get_html_shell() to do that).

Note that this automatically adds <!DOCTYPE html> to the start of the HTML shell produced, which can only be overridden with a control plugin (though you should really never do this in Perseus, which targets HTML on the web).

pub fn get_locales(&self) -> Result<Locales, PluginError>

Gets the locales information.

pub async fn get_translations_manager(self) -> T

Gets the server-side TranslationsManager. Like the mutable store, this can’t be modified by plugins due to trait complexities.

This involves evaluating the future stored for the translations manager, and so this consumes self.

pub fn get_immutable_store(&self) -> Result<ImmutableStore, PluginError>

Gets the ImmutableStore.

pub fn get_static_aliases(&self) -> Result<HashMap<String, String>, PluginError>

Gets the static aliases. This will check all provided resource paths to ensure they don’t reference files outside the project directory, due to potential security risks in production (we don’t want to accidentally serve an arbitrary in a production environment where a path may point to somewhere evil, like an alias to /etc/passwd).

pub fn take_panic_handlers( &mut self ) -> (Option<Box<dyn Fn(&PanicInfo<'_>) + Send + Sync + 'static>>, Arc<dyn Fn(Scope<'_>, ClientError, ErrorContext, ErrorPosition) -> (View<SsrNode>, View<G>) + Send + Sync>)

Takes the user-set panic handlers out and returns them as an owned tuple, allowing them to be used in an actual panic hook.

Future panics

If this is called more than once, the view panic handler will panic when called.

Trait Implementations

impl<G: Html, M: MutableStore, T: TranslationsManager> Debug for PerseusAppBase<G, M, T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<G: Html, M: MutableStore, T: TranslationsManager> TryFrom<PerseusAppBase<G, M, T>> for Reactor<G>

type Error = ClientError

The type returned in the event of a conversion error.

fn try_from(app: PerseusAppBase<G, M, T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<M: MutableStore, T: TranslationsManager> TryFrom<PerseusAppBase<SsrNode, M, T>> for Turbine<M, T>

type Error = PluginError

The type returned in the event of a conversion error.

fn try_from(app: PerseusAppBase<SsrNode, M, T>) -> Result<Self, Self::Error>

Performs the conversion.