Topcoat

Early-stage and experimental. Expect breaking changes.

A modular, batteries-included Rust web framework for server-rendered apps.

See the Getting started guide to set up a new project.

use topcoat::{
    Result,
    router::{Router, RouterBuilderDiscoverExt, page},
    view::{component, view},
};

#[tokio::main]
async fn main() {
    topcoat::start(Router::builder().discover().build()).await.unwrap();
}

#[page("/")]
async fn home() -> Result {
    view! {
        <!DOCTYPE html>
        <html>
            <body>
                hello(name: "World")
            </body>
        </html>
    }
}

#[component]
async fn hello(name: &str) -> Result {
    view! { <h1>"Hello, " (name) "!"</h1> }
}

What makes Topcoat different

Powerful, unsurprising HTML templates

The view! macro stays true to HTML and Rust. Use familiar Rust control flow as part of your templates:

view! {
    <ul>
        for post in posts {
            <li>
                <a href=(post.url) aria-current=(is_current.then_some("page"))>
                    (post.title)
                </a>
            </li>
        }
    </ul>
}

Use the topcoat fmt CLI command to automatically format view! snippets across your codebase.

Module-based routing

Topcoat can optionally infer your route tree from your app's module structure (without a build step):

src/
|-- app.rs              -> /            (and the root <html> layout)
`-- app/
    |-- about.rs        -> /about
    |-- _marketing.rs                  (layout, no URL segment)
    |-- _marketing/
    |   `-- pricing.rs  -> /pricing
    |-- posts.rs        -> /posts
    |-- posts/
    |   `-- id.rs       -> /posts/{post_id}
    `-- api/
        `-- health.rs   -> GET /api/health

Asset bundling

The bundler scans your compiled binary for asset! calls, copies (or even downloads) every file into a local asset directory, and allows Topcoat to serve them efficiently with aggressive browser caching.

const FERRIS: Asset = asset!("./ferris.png");

view! { <img src=(FERRIS)> }

Built-in Tailwind support

Enabled the tailwind feature to integrate Tailwind into your project effortlessly:

view! { <link rel="stylesheet" href=(topcoat::tailwind::stylesheet!())> }

Learn Topcoat

Start here

Getting started: create a new project, install the CLI, run the dev server.
Source code formatting: topcoat fmt for macro bodies.

Rendering

The view! macro: templating syntax, control flow, conditional attributes.
The #[component] macro: async functions as components, with child content.
The attributes! macro: reusable runtime attribute fragments.
The class! macro: space-separated class lists from static and conditional entries.

Routing

Router: pages, layouts, and API routes; manual and auto-discovered.
Module-based routing: derive the route table from your module tree.

Working with requests

Request context (Cx): the value pages, layouts, and components read from.
App context: share long-lived values across requests, keyed by type.
Cookies: read and write the request cookie jar, with signed, encrypted, and prefixed cookies.
Memoization: #[memoize] for per-request caching and fan-out dedup.
Functions, not middlewares: the recommended way to model auth and other request-scoped concerns.

Asset system

Assets: declare assets in Rust, serve them with content-hashed URLs.
Fonts: bundle and serve web fonts.
Icons: download Iconify icon sets or declare your own.

Third-party integrations

Tailwind: Tailwind CSS without Node, wired into the asset pipeline.
htmx: drive partial HTML swaps from the server with request/response header helpers.