Generators
What each `nestrs g` command writes and wires into the app that serves it, and why every route, operation and socket it generates is guarded.
Generators scaffold under crates/features/src/<name>/, register
pub mod … in crates/features/src/lib.rs, and wire what they wrote into the
app that serves it, from wherever in the workspace you run them. That app is
the one --app <name> names, else the one your directory is in, else the
workspace’s only app; with several apps and none named, the generator writes
the feature, wires nothing, and lists the apps and the imports to write. Every
command takes --dry-run (print what would change, write nothing) and a
-p path override (default: auto-discover from the current directory).
Re-running a generator is safe: it refuses to overwrite an existing feature or
adapter, and the wiring edits are idempotent.
A port is the transport-agnostic core (service + module). An adapter bolts one transport onto a port. A resource is a DB-backed CRUD port plus its HTTP adapter in one shot.
# Port only (service + module, no transport)nestrs g feature posts
# DB-backed CRUD: #[expose] entity + CrudService + guarded #[crud] controller,# its table's migration and, in the app serving it, its round trip — all from# the one column list. Bootstraps the auth adapter below when the workspace has# none — its routes name AuthnGuard/AuthzGuard, so they would not compile# without it.nestrs g resource posts title:string body:text published_at:datetime:nullable
# One #[expose] entity in an existing feature — no controller, no auth# bootstrap. The name after the slash is the entity's own when the feature's# singular is not it.nestrs g entity posts # → Post, in posts/entity.rsnestrs g entity posts/comment # → Comment
# The app's authn/authz adapter — Claims, AuthnGuard, AuthzAbility, AuthzGuard.# Run it *before* the first `g resource`, or not at all: it refuses when# `crates/features/src/authz/` already exists. It draws a random HS256 secret# into the git-ignored `.env.local` and another into `.env.test`, read only by# the test suites; the committed `.env` gets no secret. Neither is written where# a file of the same runs, `.env` included, already sets a `<PREFIX>_AUTHN__`# variable: a secret beside your own key would fail the boot.nestrs g auth
# A SeaORM migration, registered in lib.rs and migrator.rs. `create_<table>`# over a table an entity declares creates the columns its Model does, and its# key's default; any other name writes the create-table skeleton to fill. A# name registered already, or a table a registered `create_` migration creates# (`create_post` after `create_posts`), is refused: the next change to a table# takes a name of its own. An entity declaring the table in a file that does# not parse is refused too, by its line.nestrs g migration create_commentsnestrs g migration add_status_to_posts
# The framework's own migration, the outbox's table: one migrator.rs entry, no# file. The `nestrs_` prefix is the framework's: any other `nestrs_` name, and a# resource or an entity whose table would take it, is refused.nestrs g migration nestrs_outbox
# Bolt a transport onto an existing portnestrs g http posts # controllernestrs g graphql posts # resolvernestrs g ws posts # gatewaynestrs g queue posts # processor, and the outbox's migrationnestrs g schedule posts # scheduled tasksnestrs g mcp posts # MCP toolnestrs g events posts # event listener, with its event at the portg graphql and g mcp also write that transport’s authz module under
crates/features/src/authz/ when the workspace has a policy to enforce, and the
adapter imports it. It is not optional wiring: /graphql and /mcp run the guards
a module declares at their request, so without it /mcp denies every call and
/graphql runs operations with no ability attached. g ws writes none: a
gateway’s module imports AuthzModule, which g auth wrote, and that brings the
guards whose ability crosses the connection and scopes its rows.
g queue also registers the framework’s outbox migration in
crates/migrations, when the workspace keeps that crate. The queue it enables
keeps a job pushed inside a transaction in the outbox’s table until the commit,
and an app binding SeaORM beside a queue refuses to boot without the table:
nestrs run db up creates it.
Each adapter delegates to the port’s service, so a freshly-generated port plus
any adapter compiles immediately — the handler is the seam you fill in. Its
module.rs imports the port and the module providing its guards, and the
handler’s decorator brings what serves its edge (HttpModule, GraphqlModule,
WsModule, McpModule, QueueModule, ScheduleModule), so an app importing
the adapter serves it, reads its edge’s configuration and imports nothing
more; g events imports EventsModule into the
port that emits. The app’s root keeps only the bindings it chooses, and the
generator writes them there, in the same edit as the adapter, when the root has
none. The queue’s backend is one: g queue writes RedisQueueModule, which
imports the Redis connection it runs on. The data layer is the other: a #[crud]
handler — g resource’s controller, g http or g graphql over a resource
port — runs each call in the unit of work SeaOrmDatabaseModule binds, so the
generator writes it, and it imports the pool. A root already naming a binding —
bare, pinned with for_root, or a named instance — keeps its own line, as one
pinning a resource does. And the auth adapter’s token route: a generator that wrote the adapter on the way
writes AuthnHttpModule.
$ nestrs g resource posts --app blog… 3. PostsHttpModule is wired into `blog`, beside SeaOrmDatabaseModule and AuthnHttpModule.The columns g resource takes
Section titled “The columns g resource takes”Each column after the name is <name>:<type>, the field grammar Rails’ and
Phoenix’s generators share, or <name>:<type>:nullable for one a row may leave
empty; with none, a resource gets one name:string column. The key and the
three timestamps come with every table, so no list names id, created_at,
updated_at or deleted_at.
| Type | Field | Column | The round trip posts |
|---|---|---|---|
string | String, at least one character | varchar | "Title 1" |
text | String, column_type = "Text", at least one character | text | "Body 1" |
integer | i32 | integer | 1 |
bigint | i64 | bigint | 1 |
float | f64 | double precision | 1.5 |
boolean | bool | boolean | true |
uuid | Uuid | uuid | a UUID |
date | Date | date | "2026-01-01" |
datetime | DateTimeWithTimeZone | timestamptz | an instant |
One list writes three files that must agree, and a column typed four times by
hand is four chances to disagree: the entity’s field, exposed as an input of
both writes; the migration’s ColumnDef and DeriveIden variant; and the
round trip’s body, which writes a value of each column and reads each back. A
name the grammar does not read, a type it does not know, a column named twice
or a house column is refused before anything is written. A column added later
goes into the entity, and into a migration of its own — nestrs g migration add_<column>_to_<table> writes the file to fill.
Why g resource is guarded
Section titled “Why g resource is guarded”g resource emits the #[crud] + #[use_guards(AuthnGuard, AuthzGuard)] form,
and scaffolds the g auth adapter when the workspace has none. That is not
hardening you can defer: Repo filters every read by the caller’s ambient
Ability, which only the ability guard installs, so
an unguarded DB-backed controller mounts its routes and then serves nothing.
A generated resource therefore answers 401 without a token and 403 until
AuthzAbility grants a rule for its entity — the line
the generator prints. A resource meant to be readable without a login is
the same slice with one route marked #[public(Read, Entity)] and a rule in
define_visitor; see Public reads.
Before inventing a second layout, open
crates/features/src/orgs/
side by side with what the generator emitted.
Where g entity puts the file
Section titled “Where g entity puts the file”A module keeps its entities in one of two shapes, and the generator reads
which one you are in rather than asking. A feature with no entity yet gets
the lone posts/entity.rs. A feature already keeping several in
posts/entities/ gets one more file there, named for the singular —
comment.rs beside post.rs.
Growing from the first shape into the second, it moves entity.rs to
entities/post.rs (named for its table) in the same run: the moved file’s
super:: paths gain the level it gains — those SeaORM spells inside string
literals included — mod.rs declares entities and keeps re-exporting the
first entity flat, so crate::posts::Entity still names it, and every path in
the feature that named entity names entities::post. A reference it cannot
rewrite with certainty — the module imported by name, a super:: count that
does not reach the feature, an inline module in the moved file — refuses the
run before anything is written, naming its file and line.
The entity it writes names no service. #[expose(service = …)] points at the
one CrudService whose Entity is this entity, g entity
writes no service, and a plain g feature port’s service is not one — so the
link is yours to add, and the printed next steps spell the line. Reach for
g resource instead when you want the entity, the service and the guarded
controller together.
An adapter generated afterwards reads the same shape. g mcp and g graphql gate
on crate::posts::Entity, the first entity, and write no #[subject] beside it;
g graphql adds the graphql flag to the entity your CrudService names, wherever
it moved to. The service is read wherever the port’s module tree declares it —
service.rs, services/, a provider’s file beside them — and a file no mod
declares is not read, as the compiler reads none. When the service’s source leads to no file of the port, or that file
holds no #[expose(...)], the run says so in its next steps, and the flag is yours
to add. A port file that does not parse refuses the run, naming its line, with
nothing written.
g graphql over a resource carries the same guarantee
Section titled “g graphql over a resource carries the same guarantee”The GraphQL adapter for a resource port is the #[crud] resolver behind the
ability guard — #[use_guards(AuthzGuard)] alone, since AuthnGuard checks
HTTP requests only and a resolver refuses it at compile time — and it comes with
the endpoint guards that authenticate the /graphql request:
crates/features/src/authz/graphql/ plus the AuthzGraphqlModule import in the
adapter’s module.rs. That folder is not optional decoration — no controller
owns /graphql, so the guards its module declares are the only thing that
authenticates the caller and attaches the ability the resolvers read.
A generated operation is never open
Section titled “A generated operation is never open”Over a port with no entity, g graphql and g mcp still write a gated
operation: they declare the port’s capability with
#[subject] beside
its service — crates/features/src/posts/subject.rs, pub struct Post;,
written once by whichever adapter comes first — and gate the query or the tool
on it with #[authorize(Read, Post)], behind the same guards and authz module
as the resource form. It answers FORBIDDEN until your policy grants it,
ab.can(nest_rs::authz::Action::Read, crate::posts::Post), which the printed
next step spells.
A port with an entity but no service gates on that entity instead. The file is
subject.rs whatever the port’s name, so subject is one of the words
no module takes.
An operation that starts answering with rows is re-gated on their entity,
#[authorize(Read, PostEntity)], so a caller holding no grant on them is refused
rather than handed an empty answer. g entity posts
does it: the entity’s wire type takes the subject’s name, so the run retires
subject.rs and its two lines in mod.rs, and gates on crate::posts::Entity
each operation g graphql and g mcp gated on Post, in the same
transaction. The grant stays yours — the run prints the line to write in
authz/ability.rs where you granted crate::posts::Post, and until you do the
operations answer FORBIDDEN. A subject or an operation you edited beyond what
the generator wrote is yours too: the run refuses, naming the file.
A generated route or socket is never open
Section titled “A generated route or socket is never open”g http and g ws bind #[use_guards(AuthnGuard, AuthzGuard)] on the
controller or gateway over a plain g feature port too, import the transport’s
authz module, and scaffold the g auth adapter when the workspace has none, as
g resource does. A route those guards cover needs no posture of its own, and
the boot refuses one no guard covers, so an opening is always a line you write:
#[public] on the route that is open on purpose. A gateway’s guards run at the
upgrade and cover its messages the same way.
Going further
Section titled “Going further”- CLI — install, scaffold a workspace, run its tasks.
- Tutorial — the generators at work, building
postsinapps/blog/. - Authorization — the policy a generated resource
answers
403until you grant it.