Installation

This chapter gets you from "no Suprnova on this machine" to a running scaffolded project. If you're already there, jump to the Quickstart.

Requirements

• Rust 1.94.0+ for current main (the workspace uses the 2024 edition). Tagged releases have the same Rust 1.94.0 floor. Install via rustup:

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

• Node.js 20+ and npm (or pnpm/yarn/bun) for the frontend toolchain. Suprnova uses Vite 8 and your starter ships TypeScript + Tailwind v4. Install via nodejs.org or your package manager.
• A database client library that matches the driver you want to use:
  • SQLite - no extras needed; sqlite is bundled
  • PostgreSQL - libpq on most systems (often pre-installed)
  • MySQL or MariaDB - libmariadb / libmysqlclient on most systems

You don't have to choose a database now. The default scaffolder picks SQLite so a fresh app runs with zero setup.

Current main uses SeaORM 2.0, SeaQuery 1.0, and SQLx 0.9. Applications that call SeaORM directly must import ExprTrait for SeaQuery expression methods and call explicit *_raw connection methods for prebuilt Statement values. The dependency upgrade requires no application data migration.

Install the CLI

Suprnova is distributed as a Cargo project, and the CLI installer pulls the framework from git rather than crates.io (see Distribution model below). The command installs the tagged v2.1.0 release:

cargo install --git https://github.com/eas4ai/suprnova.git --tag v4.0.3 suprnova-cli

This compiles the suprnova binary and drops it into ~/.cargo/bin. Confirm it worked:

suprnova --version

You should see suprnova 0.x.x.

If suprnova isn't found, your ~/.cargo/bin isn't on PATH. Add this to your shell config:

export PATH="$HOME/.cargo/bin:$PATH"

Create a project

suprnova new scaffolds a complete project - backend + chosen frontend + Vite config + auth migrations + sample routes. It's interactive by default:

suprnova new my-app

The wizard asks for, in order:

1. Project name - skipped when you pass it as the argument (my-app)
2. Description - used in Cargo.toml
3. Author - used in Cargo.toml; defaults to your git user.name
4. Frontend framework - one of svelte (default), react, vue

If you want to skip the prompts (CI, scripted setup), pass --no-interaction and pick a frontend explicitly:

suprnova new my-app --frontend svelte --no-interaction

--no-interaction accepts the defaults for description ("A web application built with Suprnova") and author (empty). To set those, edit the generated Cargo.toml after scaffolding.

The three frontend choices each ship their own runes-on/Svelte-5, React-19, or Vue-3.5 starter. All three use Inertia v3 + Vite 8 + Tailwind v4 and pre-wire a Login/Register/Dashboard flow with session-based auth.

Suprnova also ships a slimmer API starter for service backends with no SPA:

suprnova new my-api --api

The API starter has no frontend or Inertia layer. It initializes Magnetar on the application database, installs BearerTokenMiddleware, and scaffolds password registration and login against app_users.

First run

cd my-app

# Run migrations (users, sessions, etc.)
suprnova migrate

# Install frontend dependencies
npm install              # in the project root

# Start the backend + Vite together
suprnova serve

suprnova serve runs the backend on http://127.0.0.1:8765 and Vite on http://127.0.0.1:5765. Open the backend URL: the page it serves loads its scripts and styles from the Vite dev server, so you never need to visit Vite yourself.

You should see the welcome page. Then visit /register to make an account and /login to log in.

What got scaffolded

my-app/
├── Cargo.toml          # crate manifest, two [[bin]] targets
├── .env                # local config (DB URL, app key, ports)
├── .env.example        # template for ops/CI
├── .gitignore
├── cmd/
│   └── main.rs         # the binary entry; calls Application::new().run()
├── src/
│   ├── lib.rs          # module wiring
│   ├── bootstrap.rs    # service registration (the Suprnova analogue of providers)
│   ├── routes.rs       # the routes! macro tree
│   ├── bin/
│   │   └── console.rs  # `cargo run --bin console <subcommand>`
│   ├── actions/        # single-method invokable controllers
│   ├── commands/       # `#[command]`-annotated handlers
│   ├── config/         # typed config sections (database, mail)
│   ├── controllers/    # home, auth, dashboard
│   │   ├── notes.rs    # notes list, detail and creation
│   │   └── profile.rs  # display-name updates
│   ├── middleware/     # logging, authenticate
│   ├── migrations/     # SeaORM migrators (users, sessions, etc.)
│   │   └── m20240101_000005_create_notes_table.rs
│   ├── props/          # typed flash data
│   └── models/         # `#[suprnova::model]` structs (user)
│       └── note.rs     # notes owned by a user
├── templates/
│   └── app.html        # the Inertia root document (`AppDocument` in bootstrap.rs)
├── frontend/
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── src/
│       ├── main.{tsx,ts}
│       ├── app.css
│       ├── layouts/    # persistent application and guest layouts
│       ├── components/ # shared navigation, titles and flash toasts
│       ├── pages/
│       │   ├── Home, Dashboard
│       │   ├── Notes/  # Index and Show
│       │   └── auth/{Login,Register}
│       └── types/
│           └── inertia-props.ts
└── public/
    └── assets/         # Vite production build output

The full directory tour is in Directory Structure.

Updating the CLI

The CLI lives in your ~/.cargo/bin. To update to the latest:

cargo install --force --git https://github.com/eas4ai/suprnova.git --tag v4.0.3 suprnova-cli

--force makes Cargo overwrite the existing binary.

Updating your app's framework version

A scaffolded app depends on the suprnova framework crate via a git dependency in Cargo.toml:

suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.0.3" }

A CLI pins the release tag when that tag names the commit the CLI was built from. The build reads the tag from its own checkout, or, when the checkout has no such tag, from the checkout's origin if origin is a repository on the same machine. That covers the install command above: cargo install --git ... --tag v<version> builds from a Cargo checkout that carries no tags, so the build reads the release tag from Cargo's git database on disk, without the network. Any other CLI pins its commit instead, as rev = "<commit hash>":

• A CLI built from main between two releases pins its commit because its templates can use framework API that the last release tag does not have yet. The scaffold needs the framework from the same commit.
• A CLI built from a checkout where git can read no release tag offline, such as a shallow clone or a clone of main made without tags, pins its commit even at the release. The release commit's hash names the same source as the tag.

Replace rev with a release tag when you move to a release.

To pull the latest framework changes:

cargo update -p suprnova

The git dependency tracks the named release tag. Update the tag in Cargo.toml, then run cargo update -p suprnova; your Cargo.lock records the exact commit it resolved, so builds stay reproducible between updates - there's no need to hand-pin a rev in Cargo.toml.

Distribution model

Suprnova is distributed through git, not crates.io - both the framework and the CLI install from GitHub. Each version is published as a tagged GitHub Release (e.g. v2.1.0), and the tag is what your app depends on: a scaffolded Cargo.toml pins tag = "v4.0.3" when the CLI was installed from that release, or the commit the CLI was built from otherwise (see above), and Cargo.lock records the exact commit, so builds are reproducible until you choose to move. Updating is deliberate, never incidental - bump the tag and run cargo update -p suprnova; the section on updating your app's framework version walks through it.

Editor setup

A few VS Code extensions make the experience smoother:

• rust-analyzer - the Rust language server
• Svelte for VS Code (or React/Vue if you chose those)
• Tailwind CSS IntelliSense
• Even Better TOML

rust-analyzer will index the project on first open; expect 1-2 minutes the first time, then incremental.

Next

• Quickstart - build a tiny app in 5 minutes
• Directory Structure - what's in each file the scaffolder generated
• Configuration - the .env and typed config story
• Routing - add your first route