Crate perseus_cli

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.

Packages

This is the API documentation for the perseus-cli package, which acts as a frontend for abstracting away a lot of Perseus’ internal complexity. 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.

Why is this here?

Usually, binary packages wouldn’t have API documentation like this, but the Perseus CLI uses a hybrid structure of a library and a binary, which allows it to be used as a library in applications that build on Perseus. Note that this area of using Perseus is currently almost entirely undocumented, and there may be major hiccups! If you’d like to help us out, please open a PR for the documentation you’d like to see on this front!

Modules

Structs

  • Tools
    A representation of the paths to all the external tools we need. This includes cargo, simply for convenience, even though it’s not actually independently installed.

Constants

  • PERSEUS_VERSION
    The current version of the CLI, extracted from the crate version.

Statics

  • WATCH_EXCLUSIONS
    The paths of files/folders that are excluded from the watcher system by default. These can be overriden using the custom watcher system.

Functions

  • build
    Builds the subcrates to get a directory that we can serve. Returns an exit code.
  • check
    Checks the user’s app by checking their code and building it. This will first run cargo check, and then cargo check --target wasm32-unknown-unknown, so we can error quickly on compilation errors. If those both succeed, then we’ll actually try to generate build artifacts, which is the only other place a Perseus can reasonably fail at build-time.
  • check_env
    Checks if the user has the necessary prerequisites on their system (i.e. cargo and wasm-pack). These can all be checked by just trying to run their binaries and looking for errors. If the user has other paths for these, they can define them under the environment variables PERSEUS_CARGO_PATH and PERSEUS_WASM_PACK_PATH.
  • create_dist
    Creates the dist/ directory in the project root, which is necessary for Cargo to be able to put its build artifacts in there.
  • delete_artifacts
    Deletes build artifacts in dist/static or dist/pkg and replaces the directory.
  • delete_dist
    Deletes the entire dist/ directory. Notably, this is where we keep several Cargo artifacts, so this means the next build will be much slower.
  • deploy
    Deploys the user’s app to the pkg/ directory (can be changed with -o/--output). This will build everything for release and then put it all together in one folder that can be conveniently uploaded to a server, file host, etc. This can return any kind of error because deploying involves working with other subcommands.
  • export
    Builds the subcrates to get a directory that we can serve. Returns an exit code.
  • export_error_page
    Exports a single error page for the given HTTP status code to the given location.
  • get_tools_dir
    Gets the directory to store tools in. This will preferentially use the system-wide cache, falling back to a local version.
  • get_user_crate_name
    Gets the name of the user’s crate from their Cargo.toml (assumed to be in the root of the given directory).
  • init
    Initializes a new Perseus project in the given directory, based on either the default template or one from a given URL.
  • new
    Initializes a new Perseus project in a new directory that’s a child of the current one.
  • order_reload
    Orders all connected browsers to reload themselves. This spawns a blocking task through Tokio under the hood. Note that this will only do anything if PERSEUS_USE_RELOAD_SERVER is set to true.
  • run_reload_server
    Runs the reload server, which is used to instruct the browser on when to reload for updates.
  • serve
    Builds the subcrates to get a directory that we can serve and then serves it. If possible, this will return the path to the server executable so that it can be used in deployment.
  • serve_exported
    Serves an exported app, assuming it’s already been exported.
  • snoop_build
    Runs static generation processes directly so the user can see detailed logs. This is commonly used for allowing users to see dbg! and the like in their builder functions.
  • snoop_server
    Runs the commands to run the server directly so the user can see detailed logs.
  • snoop_wasm_build
    Runs the commands to build the user’s app to Wasm directly so they can see detailed logs. This can’t be used for release builds, so we don’t have to worry about wasm-opt.
  • test
    Tests the user’s app by creating a testing server and running cargo test against it, which will presumably use a WebDriver of some kind.
  • tinker
    Runs plugin tinkers on the engine and returns an exit code. This doesn’t have a release mode because tinkers should be applied in development to work in both development and production.