Skip to content

Scaffold the app

Create apps/blog/ with nestrs new blog, start it with nestrs run dev blog, get Hello World on / — then read what the CLI generated.

You add the blog app to your workspace with the nestrs CLI — the same tool from Getting started. By the end of this page, nestrs run dev blog listens on the port written into the app’s own .env and answers Hello World on GET / — the scaffold proves itself before you write a line.

From the workspace root:

  1. Scaffold the app and the feature it serves.

    Terminal window
    nestrs new blog

    Inside an existing workspace this writes apps/blog/ and the next free HTTP port into apps/blog/.env (see nestrs new blog in the CLI docs). The command refuses to overwrite if the folder already exists.

  2. Start it under bacon (restarts on save).

    Terminal window
    nestrs run dev blog
  3. Hit the root route — use the port from apps/blog/.env.

    Terminal window
    $ curl -i http://localhost:3001/
    HTTP/1.1 200 OK
    Hello World

nestrs new blog does not ask you to hand-edit the root Cargo.toml members list — workspace apps are discovered from apps/*. It writes a thin app plus the feature behind that greeting: main.rs boots the framework, module.rs imports one feature module’s HTTP adapter, and there is no controller.rs or service.rs in the app crate — those live in crates/features/, which is where posts lands from the next page onward.

  • Directoryapps/blog/
    • .env the port
    • Cargo.toml
    • Directorysrc/
      • lib.rs
      • main.rs
      • module.rs
    • Directorytests/
      • integration/main.rs
      • e2e/main.rs
  • Directorycrates/features/src/blog/
    • mod.rs
    • module.rs
    • service.rs the greeting
    • Directoryhttp/
      • mod.rs
      • module.rs
      • controller.rs #[public] GET /

The blog feature is a placeholder with one job: proving the wiring works end to end on the first run. Delete it once posts is serving something real.

apps/blog/Cargo.toml
[package]
name = "blog"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
publish = false
[dependencies]
features.workspace = true
nest-rs = { workspace = true, features = ["opentelemetry"] }
anyhow.workspace = true
[dev-dependencies]
nest-rs = { workspace = true, features = ["testing"] }
tokio.workspace = true
[lints]
workspace = true

One nest-rs dependency, and it stays one for the rest of this tutorial: the capabilities arrive as features on it ([workspace.dependencies] in the root manifest is where the list lives). The app adds opentelemetry, which its main installs; the dev-dependency adds testing, the harness, to the tests alone, so no release binary carries it. anyhow is there because main.rs writes it, and tokio only for the tests, which write #[tokio::test]: #[nest_rs::main] builds the runtime main runs on itself.

The root module lists the edges the app serves. BlogHttpModule, the feature’s HTTP adapter, lists a controller, which brings HttpModule, so the app names no transport: it would write HttpModule::for_root(..) only to pin a setting in code. Every <PREFIX>_HTTP__* setting comes from the environment — the listen port from the app’s own .env:

apps/blog/src/module.rs
use nest_rs::core::module;
use features::blog::BlogHttpModule;
#[module(
imports = [
BlogHttpModule,
],
)]
pub struct BlogModule;
apps/blog/.env
NESTRS_HTTP__PORT=3001
NESTRS_AUTHN__ISSUER=http://localhost:3001
NESTRS_AUTHN__AUDIENCE=http://localhost:3001

nestrs new blog picks the next free port: 3001 beside hello’s 3000, and another if other apps already hold it. Its origin is also the issuer and the audience of the tokens blog mints and accepts once its routes authenticate, from Expose over HTTP: every token names both, and the app does not start without them. The workspace’s own .env* files are shared by every app; apps/blog/.env is read over them under the development and test profiles, so a value that is blog’s alone lives there (an app’s own files).

BlogModule has no providers = [...] list. A root module composes feature modules and lets each own its providers; what a root provides itself is app-wide — the reference root lists one, GlobalInterceptors<(AuditInterceptor,)>, the audit trail around every route it serves. Note the two BlogModules: this one is the app’s composition root, and features::blog::BlogModule is the feature’s own. Two crates, no collision — the app only ever names the …HttpModule edge.

apps/blog/src/main.rs
use anyhow::Result;
use nest_rs::core::App;
use nest_rs::opentelemetry::OpenTelemetry;
use blog::BlogModule;
#[nest_rs::main]
async fn main() -> Result<()> {
let _otel = OpenTelemetry::init()?;
App::builder()
.module::<BlogModule>()
.build()
.await?
.run()
.await
}

OpenTelemetry::init() is the app’s whole telemetry: it installs the console, and an OTLP exporter for each signal the deployment’s OTEL_* point at — none on your machine, where the console is all there is. It stays the first line of main, so its guard flushes what is left when main returns; there is no module to import for it, and nothing for a test to call (OpenTelemetry). App::builder() runs the four boot phases — seeds, collect, factories, register — verifies the access graph, then .run() blocks on the transports. #[nest_rs::main] builds the runtime all of it runs on, and once run returns it ends the process within the shutdown budget rather than waiting on whatever the way down abandoned. The CLI also writes src/lib.rs (re-exporting BlogModule for the tests in Test it end to end), a smoke test that asserts the greeting, and an empty tests/e2e/main.rs. The e2e suite has to exist even while empty: nestrs run test integration filters on not binary(e2e), and nextest rejects a filterset naming a binary the workspace does not have.

  1. From the workspace root:

    Terminal window
    $ nestrs run dev blog
    Compiling blog v0.1.0
    Running `target/debug/blog`
    INFO nest_rs::app: app starting app="blog" version="0.1.0" framework="7.0.0"
    INFO nest_rs::routes: mounted host="BlogController" method="hello" verb="GET" path="/"
    INFO nest_rs::app: app ready transports="http" addresses="0.0.0.0:3001"

    The route table prints on every boot, and app ready shows the port from your apps/blog/.env.

  2. In another terminal:

    Terminal window
    $ curl -i http://localhost:3001/
    HTTP/1.1 200 OK
    Hello World
  3. Stop the server with Ctrl-C.

That 200 is the checkpoint: the transport is mounted, the DI graph resolved, the access graph passed, and a controller reached your browser. Everything after this page replaces the greeting with real work.

  • A blog app under apps/blog/, scaffolded by nestrs new blog.
  • A BlogModule that imports one feature’s HTTP adapter, which brings the HTTP transport.
  • A blog feature answering Hello World on / — proof the framework boots and serves end to end.
  • Declare the entity — the next step: define the Post entity with #[expose].
  • CLI — the reference for nestrs new and the rest of the CLI surface.