Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting Started

Welcome to the Rullst Getting Started guide!

Your goal: install the matching preview CLI, generate a small application, open it locally and make your first change. Prefer to write the first route yourself? Use Zero to Hello Rullst.

Rullst is a strictly typed Rust framework suite for full-stack applications, designed around explicit APIs, measurable performance, and defense-in-depth defaults.

1. Installation

First, ensure you have Rust installed. The official and recommended way is to visit rustup.rs.

For macOS and Linux:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

For Windows: Download and run rustup-init.exe from the website.

Next, install the Rullst CLI from the same release train as the framework. The registry command installs the latest published release; it does not install the unreleased v12 source documented by this branch:

cargo install cargo-rullst

To evaluate v12 before its first RC is published, clone this repository and install the CLI from that exact checkout instead:

git clone --branch main https://github.com/Rullst/Rullst.git
cd Rullst
cargo install --locked --path cargo-rullst
cd ..

During this source-only phase, the pre-release CLI reuses the exact checkout from which it was compiled, even when project creation is invoked from another directory, provided that checkout has not been moved or deleted. Generated manifests therefore contain absolute path dependencies and are not portable yet. Running from the repository root remains an explicit fallback. Once an immutable v12 RC exists on crates.io, install that exact CLI version and use its matching registry packages instead.

2. Creating Your First Project

We have completely redesigned the project creation experience. Instead of remembering complex flags, just run:

cargo rullst

The Rullst App Creator will launch an interactive wizard. The example below creates a Portfolio while v12 remains unpublished:

  1. Select Create New App.
  2. App Name: Provide a simple lowercase name (e.g., my_portfolio).
  3. Starter Blueprint: Choose Portfolio. Labels and decorative suffixes can change; use the blueprint name as your reference.
  4. Choose your primary database. SQLite is the simplest local first run; PostgreSQL, MySQL and MariaDB require their database service to be running.
  5. Leave optional persistence capabilities empty unless you need an add-on. That selector accepts zero or more choices; it is not another required database.
cd my_portfolio
cargo rullst dev

Open the local URL reported by the command. Find the generated page code, change a heading and save. Confirm that the changed page appears after the successful rebuild/restart. Stop development with Ctrl+C before moving or removing the project directory.

Prefer a small deterministic starter without navigating the wizard?

cargo rullst new first_app --default --blueprint blank --database sqlite \
  --skip-initial-migration
cd first_app
cargo rullst dev

The first source build can take several minutes. --skip-initial-migration defers the generator’s bootstrap work; the development command runs the initial migration before starting a generated database-backed app. Never point this learning project at a production database.

Tip

The cargo rullst dev command compiles the project and starts the local server. Saving changes triggers a real rebuild and supervised process restart; a failed build leaves the previous application serving. The same-origin browser client refreshes after the new process responds with its generation marker. In-memory state resets. No hot-reload scaffold option is required. See the CLI reference.

Rullst v12 deliberately generates one audited application profile: Active Record with server-rendered html! views and HTMX enhancement. The framework still exposes lower-level repository and client-runtime foundations for application-owned integration. See the Architecture Choices Guide.

3. Rullst Blueprints Showcase

The Rullst framework accelerates your development by providing Blueprints. A Blueprint is a highly-polished, pre-built application template that serves as the foundation for your project.

When you run cargo rullst, the wizard asks you to select a blueprint. The blueprints use the Rullst color scheme and server-rendered HTML/HTMX patterns; allocation and latency depend on the generated page and runtime.

1. Blank Starter

Use Case: Custom, from-scratch development. This is the minimal template powered by server-rendered html! views and HTMX without a project-local JavaScript bundle. It includes a simple reactive counter to demonstrate server-driven communication. Other frontend foundations remain available as application APIs, but v12 does not advertise them as equivalent generated blueprints.

2. Portfolio 🔥

Use Case: Developer showcases and personal branding. Status: HOT! A visually stunning, glassmorphic portfolio template designed specifically for Rullst/AI developers. It includes:

  • Profile Settings in Nexus CMS (/nexus): Edit your name, title, bio, email, website URL, avatar photo, GitHub, and LinkedIn links live without changing code.
  • A responsive sidebar and Hero section with glowing glassmorphism effects.
  • Interactive Experience timeline and Skills tags.
  • Project cards showcase with live external links.

3. LMS Platform Starter

Use Case: Online learning products and course platforms. The complete profile is a bounded learning-domain foundation featuring:

  • School-scoped curriculum, enrollment, progress and versioned publication.
  • Quizzes, learning activities, assignments/rubrics, completion records and database-verifiable certificates.
  • Roles, leaderboard updates, transactional outbox/workers, scheduling and localized in-app notifications.
  • Accessible server-rendered catalog, course and media-player shells with explicit source, caption and transcript admission rules.

It remains a starter rather than a finished education product. Upload hosting, media transcoding and signed delivery, advanced/localized search, billing-linked entitlements, distributed failover, native offline playback, real-browser/WCAG evidence and PostgreSQL/MySQL isolation evidence remain application or roadmap work. Smaller auth, auth,learning and auth,learning,assessment profiles are available when the complete domain scaffold is unnecessary.

4. SaaS App Starter

Use Case: Subscription-based products and billing. An opinionated SaaS starting point, pre-wired with:

  • User authentication (login, signup, session management).
  • Stripe pricing panels and subscription checkout views.
  • Secure user dashboard.

5. Blog / Press

Use Case: Content creation and articles. A database-backed, server-rendered blog/CMS blueprint. It features:

  • A beautiful article reading view with typography optimized for readability.
  • Article CRUD and a server-rendered reading view. Markdown parsing is not part of the current generated starter.
  • SEO-friendly metadata injection.

6. ERP Pocket

Use Case: Business management, stock, and inventory tracking. An inventory-oriented back-office starter. It features:

  • A complex relational database schema (Products and Orders).
  • Full CRUD operations with HTMX.
  • A sleek, split-pane dashboard for simultaneous product listing and order creation.

Tip

Blueprint evolution: Blueprints are continuously checked by generator smoke tests. Treat generated code as an application starting point: inspect its configuration and rerun cargo check and security tests after customization.

Local Studio and Nexus access

The Blog, Portfolio, LMS, ERP, and SaaS blueprints expose visible buttons for both control surfaces during local development:

  • Nexus is mounted at /nexus and accepts only a verified loopback peer in a debug build, so the first local click needs no placeholder password.
  • Studio starts as a separate debug-only service at http://127.0.0.1:5555.

This convenience cannot be enabled in a release binary through RULLST_ENV or the legacy APP_ENV alias. A release build does not start the generated Studio task and requires unique NEXUS_ADMIN_USERNAME and NEXUS_ADMIN_PASSWORD values before Nexus can be constructed. Put production Nexus behind a verified TLS boundary and explicit application authorization; do not expose Studio publicly.

5. Database configuration and specialized stores

The wizard deliberately makes two separate decisions:

  1. Choose the primary SQLx Active Record backend: SQLite, PostgreSQL, MySQL, or MariaDB. MariaDB uses the MySQL wire protocol but has its own executable container contract. The blank/API starter can instead select Turso/libSQL as its primary typed ORM.
  2. Optionally add Turso/libSQL edge SQL to a SQLx application, MongoDB documents, DuckDB analytics, or SurrealDB documents/graph reads. These use explicit capability APIs and do not silently replace the primary pool.

After generation, the default flow compiles the new application once and runs its initial migration. A clean first build can take several minutes for larger blueprints. Use --skip-initial-migration when the network database is not yet configured, then run cargo rullst db:migrate from the generated project.

The non-interactive flags mirror the second step:

cargo rullst new edge_app --default --database mariadb --turso --mongodb \
  --skip-initial-migration

Automation can pin the supported blueprint, database and optional runtime capabilities. The v12 application architecture is intentionally fixed to Active Record plus server-rendered html!/HTMX:

cargo rullst new learning_portal --default --blueprint lms \
  --database postgres --ai \
  --skip-initial-migration

For a blank application with no primary relational database, use the explicit --no-database flag. It cannot be combined with --database. Generated SQLx profiles disable Rullst’s umbrella defaults and select exactly one strict relational backend, so a chosen PostgreSQL/MySQL/MariaDB profile is not accidentally compiled through an implicit SQLite default.

To create a Turso-primary API using the current bounded blank starter:

cargo rullst new edge_app --default --api --database turso \
  --skip-initial-migration
cd edge_app
cargo rullst db:migrate

The generated .env selects a persistent, real-SQL offline fallback and does not invent a SQLx DATABASE_URL:

TURSO_DATABASE_URL=mock_local
TURSO_AUTH_TOKEN=
TURSO_OFFLINE_PATH=turso-development.db

To use Turso Cloud, put the token in its own variable rather than in the URL:

turso db create my-app-db
turso db tokens create my-app-db

TURSO_DATABASE_URL=libsql://my-app-db-username.turso.io
TURSO_AUTH_TOKEN=replace-with-a-secret-token

The familiar derive explicitly selects the Turso backend:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, rullst_orm::Orm)]
#[orm(table = "users", backend = "turso")]
struct User {
    id: i64,
    name: String,
}
}

User::all(), find, save, create, delete, count, filtering, ordering and pagination then execute through the primary TursoOrm store. make:model --migration, make:migration, db:migrate, db:status, and db:rollback preserve this backend. The current first-class scaffold contract is deliberately limited to the blank/API profile; SQLx-specific LMS, SaaS, blog, portfolio, and ERP blueprints reject --database turso until ported. Transparent embedded-replica synchronization is not claimed.

TursoStore remains available for prepared SQL, bounded result materialization, transactions and checksummed migrations in either primary or additive configurations. See Polyglot Persistence for complete setup, security constraints and examples for every optional store.