Installation

Navree is a Rust framework, so you need a Rust toolchain and the navree command-line tool. The CLI creates applications, generates code and runs the development loop. Your application is an ordinary Cargo package that depends on the navree crate.

Requirements

You don't need OpenSSL, CMake or NASM: TLS is rustls with the ring provider everywhere. You don't need a database server either. New apps use SQLite, and PostgreSQL is an opt-in feature (see Database: getting started).

Installing the CLI

cargo install --git https://github.com/NavreeHQ/navree navree-cli

git clone https://github.com/NavreeHQ/navree
cargo install --path navree/crates/navree-cli

Check that it works:

navree --version

navree 0.1.0

Where new apps get Navree from

The CLI doesn't depend on the framework; it writes the dependency into your app's Cargo.toml. navree new picks it like this:

1. With --navree-path <path>, the Navree checkout at that path (the repository, or its crates/navree directory).
2. Otherwise, the checkout the CLI was built from, when it still exists. After cargo install --path, that is your clone. After cargo install --git, it is Cargo's own copy of the repository under ~/.cargo/git/checkouts.
3. Otherwise, the published crate: navree = "0.1.0".

Until the crates are published, the third case fails to build. For an app you plan to keep, clone the repository and either install the CLI from the clone or pass --navree-path. Cargo's Git checkouts are a cache that Cargo can clean up.

Adding Navree to an existing project

To use Navree in a Cargo package you already have, add it from the Git repository:

cargo add --git https://github.com/NavreeHQ/navree navree

This adds a Git dependency with every module, since the full feature is on by default. The derive macros of serde, SeaORM and garde name their own crates, so add serde, sea-orm and garde too; a new app's Cargo.toml shows the versions and features.

Creating an application

navree new creates an app in a new directory:

navree new blog

Created blog in /home/you/code/blog
It depends on navree at /home/you/code/navree/crates/navree.

Next steps:
  cd blog
  navree key:generate     # then set APP_KEY in .env
  navree dev              # http://127.0.0.1:8080/api/docs

The name must start with a lower-case letter and use lower-case letters and digits separated by single - or _; Rust keywords and names such as std, test and navree are refused. The directory must not exist, or must be empty. navree new doesn't run Cargo or git init.

The app is complete and working: a root module with every common platform module configured, JWT authentication at /api/auth/*, roles and abilities, an example users module, OpenAPI docs and tests. Directory structure walks through every file.

Options

navree new blog --ui next --navree-path ~/code/navree

Running the application

Generate an application key first. It encrypts data and signs tokens; without it, every restart signs every user out.

cd blog
navree key:generate

base64:G60q3lWREHaFECJUwNhN58ArvmrSl0sptSaOEWgeBLk=

The first run compiles the framework, which takes a few minutes; later builds are incremental. The command boots the app, so log lines may appear before the key. Paste the key into .env:

APP_KEY=base64:G60q3lWREHaFECJUwNhN58ArvmrSl0sptSaOEWgeBLk=

Then start the development server:

navree dev

navree dev builds the app, starts its serve command and watches the code. When a file in src/, config/ or migrations/ changes, or Cargo.toml, .env or build.rs does, it rebuilds and restarts the server. If a build fails, the previous build keeps serving. With a web/ front end it also runs npm run dev there (or pnpm/yarn, chosen by the lockfile).

The API listens on http://127.0.0.1:8080. Open http://127.0.0.1:8080/api/docs for the generated API reference, or check the health endpoint:

curl http://127.0.0.1:8080/health/live

{"status":"up"}

Dev server options

Running the app's own commands

Every command other than new, make:* and dev belongs to your app's binary. navree <command> runs cargo run --quiet -- <command> in the app, so these are the same:

navree migrate
cargo run --quiet -- migrate

navree list prints every command your app has. Don't use navree help for that: it prints the CLI's own help. Your app's commands are covered in Console commands and the CLI.

Next steps