Propel rocketboost.rs

Installation and configuration

Propel is a Rust crate that works with Rocket. It needs a Rust toolchain and, for assets, Node.js.

Requirements

  • Rust, stable, with Cargo.
  • Node.js 22.12 or newer, or 20.19 or newer, for Vite and Tailwind.

Add Propel to your project

Add Propel and Rocket to Cargo.toml. Use the same Rocket revision as Propel, so the project has one copy of Rocket:

[dependencies]
rocket = { git = "https://github.com/rwf2/Rocket", rev = "3a54d079" }
propel_rocket = { git = "https://github.com/lajennylove/propel", rev = "600a609ae8046604160bbf9837a6258c0c30d04e" }

Propel is not on crates.io yet, so it comes from git. Pin rev to a commit you have tested.

Render a view

A route builds the context for its view and returns the rendered page:

#[get("/posts")]
fn posts() -> PropelView {
    PropelView::render("posts.index", &PostsIndex { posts: all_posts() })
}

The view name posts.index is the file resources/views/posts/index.propel. Dots are folder separators.

Project layout

your-app/
├── Cargo.toml
├── src/              routes and view contexts
├── resources/
│   ├── views/        .propel templates
│   │   ├── layouts/app.propel
│   │   └── posts/index.propel
│   └── css, js, images, fonts for Vite
├── public/           built files (generated, not committed)
├── package.json
└── vite.config.js

Views are read from resources/views/, and built files from public/, both relative to the folder you run the app from. There is no configuration file yet.

Run it

npm install
npm run dev     # Vite, in one terminal
cargo run       # the Rocket app, in another

Hot reload

Edits show up in two ways, and the two cost different amounts of work:

  • Views (resources/views/**/*.propel) are compiled into the binary when it builds. Run bacon instead of cargo run: it watches the views too, and it rebuilds and restarts the server on each save.
  • Rust code (src/) needs a rebuild, and bacon does it on each save.
  • CSS and JavaScript come from the Vite dev server, which npm run dev starts. It applies changes without a page reload, and it reloads the page when a view changes.

Without npm run dev, the page loads the built files from public/build, so run npm run build first.

Release builds

cargo build --release compiles each view into the binary, through a build.rs file. The binary then needs no resources/views folder. The PropelView::render call that reads views from disk exists in development builds only, so a release app returns each compiled view with PropelView::from_result. The production guide lists the steps and the caveats.

A note on the example app

This site is the example app in examples/propel of the Rocket repository. The navigation and the page wrapper that adds it to each view are part of the app for now. Propel will provide them later.