Skip to content

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.

Terminal window
# 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.rs
nestrs 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_comments
nestrs 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 port
nestrs g http posts # controller
nestrs g graphql posts # resolver
nestrs g ws posts # gateway
nestrs g queue posts # processor, and the outbox's migration
nestrs g schedule posts # scheduled tasks
nestrs g mcp posts # MCP tool
nestrs g events posts # event listener, with its event at the port

g 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.

Terminal window
$ nestrs g resource posts --app blog
…
3. PostsHttpModule is wired into `blog`, beside SeaOrmDatabaseModule and AuthnHttpModule.

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.

TypeFieldColumnThe round trip posts
stringString, at least one charactervarchar"Title 1"
textString, column_type = "Text", at least one charactertext"Body 1"
integeri32integer1
biginti64bigint1
floatf64double precision1.5
booleanboolbooleantrue
uuidUuiduuida UUID
dateDatedate"2026-01-01"
datetimeDateTimeWithTimeZonetimestamptzan 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.

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.

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.

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.

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.

  • CLI — install, scaffold a workspace, run its tasks.
  • Tutorial — the generators at work, building posts in apps/blog/.
  • Authorization — the policy a generated resource answers 403 until you grant it.