Tasks
The Quick Start guide builds a simple end-to-end application using Stately. The Tasks demo takes a bit further but still keeps it dead simple. Almost nothing on the UI side will change, yet simple additions to the backend result in a more complex application with more capabilities.
The only shortcoming of this demo is that it doesn't follow through with some important additional concepts, like nesting Link<T> which leverage recursive references, api state composition across different sub-routers, and more advanced concepts. The goal instead is to demonstrate how extending an application's capabilities works alongside what Stately already provides. We'll save the more advanced concepts for the advanced guide.
Goal
The goal of this guide is to demonstrate how simply adding entities to the backend, in this case Tasks and Users, requires almost no changes to the UI. In fact, any changes to the UI were done to enhance the UI, otherwise the quick start's UI would work out of the box. To that end, we will add a new page, Dashboard, and show how to configure it against stately's configuration options, automatically including it in the sidebar, and accessing api endpoints using stately provided functionality. That new endpoint, /metrics, demonstrates how to listen in on CRUD operations, providing additional capabilities across the stack.
What We're Building
A simple task management application with:
- A
Taskentity with name, description, and status - A
Userentity with name, title, and status - CRUD API endpoints
- A React UI for listing and creating tasks
The folder structure will assume:
Backend Setup
1. Create a New Rust Project
2. Add Dependencies
Update your Cargo.toml:
3. Define Your Entities
Create src/state.rs:
4. Create the API
Create src/api.rs:
5. Wire Up the Main Entry Point
Update src/main.rs:
6. Generate OpenAPI Spec
Add a binary target to generate the OpenAPI spec. Create src/bin/openapi.rs:
Update src/lib.rs:
Generate the OpenAPI spec:
7. Run the Backend
Your API is now running at http://localhost:3000. Test it:
Frontend Setup
This example uses React Router for routing, but Stately works with any routing library (e.g., TanStack Router, Next.js App Router). Routing helpers are planned for a future release.
1. Create a React Project
2. Install Dependencies
Install stately and additional packages
import { PackageManagerTabs } from '@theme';
Install the stately and ui packages:
In this demo, we are installed @statelyjs/ui since we will leverage base ui components, which @statelyjs/stately doesn't re-export.
Install required peer dependencies:
Since we'll be leveraging tailwind classes, let's get tailwind setup as well:
3. Generate TypeScript Types
Assuming openapi.json was created in the root directory, generate types:
4. Create the Stately Runtime
Create ui/src/lib/stately.ts:
5. Set Up Providers
Update src/main.tsx:
6. Configure Tailwind CSS
Stately requires Tailwind CSS v4. Create src/index.css:
The @source "./node_modules/@statelyjs" directive tells Tailwind to scan all Stately packages for utility classes. This single directive covers @statelyjs/stately, @statelyjs/ui, and any plugins you add.
Update vite.config.ts:
7. Create the Dashboard Component
Create src/Dashboard.tsx:
8. Create the App Component with Routes
Update src/App.tsx:
9. Run the Frontend
Open http://localhost:5173 to see your application. You now have:
- Dashboard at
/- A simple landing page - All Entities at
/entities- Browse all entity types - Task List at
/entities/task- List, create, and delete tasks - Create Task at
/entities/task/new- Form to create a new task - View Task at
/entities/task/:id- View task details - Edit Task at
/entities/task/:id/edit- Edit an existing task
What Just Happened?
-
Backend: You defined
TaskandUserentities with#[stately::entity]and a state container with#[stately::state]. The#[stately::axum_api]macro generated complete CRUD endpoints. -
OpenAPI: The backend generated an OpenAPI spec describing all your entities and endpoints.
-
Codegen: The Stately CLI parsed the OpenAPI spec and generated TypeScript types and schema definitions.
-
Frontend: The Stately runtime and pre-built pages provided:
- Type-safe API client via
openapi-fetch - Complete CRUD UI with list, detail, create, and edit views
- Auto-generated forms based on your entity schemas
- Navigation sidebar with entity types
- Responsive layout with header and breadcrumbs
- Type-safe API client via