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.
Create the app
Section titled “Create the app”From the workspace root:
-
Scaffold the app and the feature it serves.
Terminal window nestrs new blogInside an existing workspace this writes
apps/blog/and the next free HTTP port intoapps/blog/.env(seenestrs new blogin the CLI docs). The command refuses to overwrite if the folder already exists. -
Start it under
bacon(restarts on save).Terminal window nestrs run dev blog -
Hit the root route — use the port from
apps/blog/.env.Terminal window $ curl -i http://localhost:3001/HTTP/1.1 200 OKHello World
What the CLI created
Section titled “What the CLI created”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.
[package]name = "blog"version.workspace = trueedition.workspace = truerust-version.workspace = truepublish = false
[dependencies]features.workspace = truenest-rs = { workspace = true, features = ["opentelemetry"] }anyhow.workspace = true
[dev-dependencies]nest-rs = { workspace = true, features = ["testing"] }tokio.workspace = true
[lints]workspace = trueOne 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:
use nest_rs::core::module;
use features::blog::BlogHttpModule;
#[module( imports = [ BlogHttpModule, ],)]pub struct BlogModule;NESTRS_HTTP__PORT=3001NESTRS_AUTHN__ISSUER=http://localhost:3001NESTRS_AUTHN__AUDIENCE=http://localhost:3001nestrs 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.
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.
Run it again
Section titled “Run it again”-
From the workspace root:
Terminal window $ nestrs run dev blogCompiling blog v0.1.0Running `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 readyshows the port from yourapps/blog/.env. -
In another terminal:
Terminal window $ curl -i http://localhost:3001/HTTP/1.1 200 OKHello World -
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.
What you have now
Section titled “What you have now”- A
blogapp underapps/blog/, scaffolded bynestrs new blog. - A
BlogModulethat imports one feature’s HTTP adapter, which brings the HTTP transport. - A
blogfeature answeringHello Worldon/— proof the framework boots and serves end to end.
Going further
Section titled “Going further”- Declare the entity — the next step: define the
Postentity with#[expose]. - CLI — the reference for
nestrs newand the rest of the CLI surface.