Topcoat
The full full-stack framework for Rust
Topcoat is a modular, batteries-included Rust framework for building full-stack apps. It prioritizes simplicity and productivity. See Learn Topcoat to get started, or the Roadmap for what's coming next.
Early-stage and experimental. Expect breaking changes.
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
Client reactivity without the boilerplate
Topcoat renders all markup on the server: components can be async and query the database directly, eliminating all the traditional boilerplate needed for a separate API layer. Interactivity does not have to cost a round-trip, though. A $(...) expression is ordinary type-checked Rust that Topcoat evaluates on the server for the initial render and also translates to JavaScript, so it re-runs instantly in the browser. No wasm bundle, no client build step:
view! {
signal open = false;
// Runs entirely in the browser; no server round-trip.
<button @click=$(|_e| open.set(!open.get()))>"What is Topcoat?"</button>
<p :hidden=$(!open.get())>"A full-stack Rust framework."</p>
}When an update does need the server, like fresh search results, mark the component as a #[shard]. Topcoat re-renders it on the server whenever one of its $(...) arguments changes and swaps the new HTML in place:
#[component]
async fn search() -> Result {
view! {
signal query = String::new();
<input @input=$(|e: Event| query.set(e.target.value))>
// Updates as the user types.
search_results(query: $(query.get()))
}
}
#[shard]
async fn search_results(cx: &Cx, query: String) -> Result {
view! {
<ul>
// Your own server-side code, like a database query:
for product in search_products(cx, &query).await? {
<li>(product.name)</li>
}
</ul>
}
}Powerful, unsurprising HTML templates
The view! macro stays true to HTML and Rust. Use familiar Rust control flow as part of your templates:
view! {
<nav>
for item in nav_items {
<a
href=(item.url)
if item.url == current_path {
aria-current="page"
class="active"
}
>
(item.label)
</a>
}
</nav>
}Use the topcoat fmt CLI command to automatically format view! snippets (and other macros) 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
Premade components you can edit
Topcoat UI is a component library based on Tailwind inspired by shadcn/ui. Components are copied into your project via the topcoat ui CLI command, meaning you can freely change their design and functionality to fit your use case:
#[component]
async fn delete_card() -> Result {
view! {
card(
card_header(
card_title("Delete workspace")
card_description(
"This permanently removes the workspace and all of its data."
)
)
card_footer(
attrs: attributes! { class="justify-end" },
button(variant: ButtonVariant::Ghost, "Cancel")
button(variant: ButtonVariant::Destructive, "Delete workspace")
)
)
}
}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)> }Topcoat also ships with utilities for web fonts and icons, as well as easy integrations for Fontsource (Google Fonts) and Iconify.
Built-in Tailwind support
Enable the tailwind feature to integrate Tailwind into your project:
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 fmtfor 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.
- Memoization:
#[memoize]for per-request caching and fan-out dedup. - Functions, not middlewares: the recommended way to model auth and other request-scoped concerns.
- Cookies: read and write the request cookie jar, with signed, encrypted, and prefixed cookies.
- Sessions: bring-your-own-storage session authentication: login/logout lifecycle, sliding expiration, and token rotation.
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.
Client reactivity
- The runtime: signals,
$(...)expressions,@event handlers, and:bind attributes. - Expressions: the dual Rust/JavaScript expression language and its vocabulary.
- Procedures: async server functions callable from the browser.
- Shards: components that re-render on the server when their arguments change.
Miscellaneous
- Topcoat UI: premade components vendored into your project for you to edit.
- Mail: declare mail with the
mail!macro, deliver through SMTP, file, or in-memory transports.
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.
- Alpine AJAX: drive partial HTML swaps from the server with Alpine AJAX's request-header conventions.
- Datastar: patch elements and signals into the page over server-sent events.
Roadmap
Planned features we'd like to bring to Topcoat. Have an idea? Open an issue.
-
topcoat newCLI command to bootstrap pre-configured projects - Static export
- (More) reactivity (
topcoat-runtime) - More Topcoat UI components, full "blocks" e.g. sign-in form
- Better Toasty integration (safely create/update records from forms without listing out all the fields)
- Validations
- Localization support
-
OpenAPIendpoints - Sitemaps
- Docs for how to deploy Topcoat
- Pre-rendering for static pages
- Streaming SSR / Suspense
- Client-side navigation + prefetching
-
WebTransport - Image optimization / resizing
- Markdown support
- Easier-to-use middlewares like rate-limiting, compression, etc.
- Authentication
- Background jobs
- Islands
