Skip to content

What runs differently

What a NestJS habit meets underneath NestRS — security by composition, a boot that refuses, no forwardRef, no reflection — and what you will not find.

Coming from NestJS maps the vocabulary. This page is where the machine underneath diverges: what the framework holds for you that a NestJS app holds by habit, and what you will reach for and not find, each for a reason Rust gives.

Security is structural, not per-decorator discipline

Section titled “Security is structural, not per-decorator discipline”

In NestJS, authorization is a habit: you remember to add @UseGuards and a policy check on each route, and a forgotten one is a silent hole. NestRS moves the guarantee into composition. Once a feature imports the database and authz modules, every read through the data layer is filtered and every mutating write is gated, and each row a unit answers is judged for its caller where it is built. A unit naming nothing reads nothing a grant guards, so the line you forget fails closed.

You still bind guards explicitly with #[use_guards(...)], and every posture stays greppable as one #[authorize] or #[public] site — but forgetting the filter on a query is a category error the framework prevents, not a review catch.

APP_GUARD binds a NestJS guard once, in a module, for the whole app — and a controller has no way to say it depends on that binding, so the app that forgets it serves the controller open. NestRS declares the app’s pool in the module main boots, GlobalGuards<(...)> — never in a feature, which would choose what covers every route — and an HTTP route no guard identifying a caller covers — not the global pool, not a #[use_guards] on its controller or itself, a rate limit counting for nothing — refuses the boot unless it says #[public]. The refusal names every such route, so the omission is a failed start, never an open route.

Declaring the guard on the controller, resolver or gateway that needs it is still the convention, because it lets a feature crate travel to a binary with no global pool and boot there. Listing it at both scopes costs nothing: the Layer System dedups every layer by TypeId, so a guard listed twice resolves once and runs once per unit.

forwardRef(() => OtherService) exists because JavaScript modules let two files import each other and resolve the tie at runtime — NestJS then needs a way to defer one side of a cycle it cannot see until it runs. Rust does not offer the tie in the first place. Cargo refuses a dependency cycle between crates outright, so the layering you drew is the layering you get.

Two modules of one crate may still import each other. That cycle is harmless until a provider crosses it: one of the two modules registers before the other’s providers exist, so a provider injecting across the cycle has nothing to be built from. The boot refuses it by name (UnbuiltProviderError), with the edit to make:

module `UsersModule`: `UsersService` was never built — it needs `PostsService`, which nothing had registered when `UsersModule`'s providers were built; `UsersModule` and `PostsModule` import each other, so one registers before the other's providers exist: move what both need into a module both import

When the providers also wait on each other — PostsService injecting UsersService back — no layout of modules can order them, and the boot names the cycle instead (ProviderCycleError). It does so whichever modules list them and whatever their scope, a request-scoped or transient cycle included, before any request would resolve it, and the error carries the remedy:

module `PostsModule`: singleton provider cycle `PostsService` → `UsersService` → `PostsService` — break it by moving what both need into a third provider both inject, by passing the value as a method argument, or by publishing an event one side listens to

That remedy is the point. A cycle is a design signal — each side owns half of what the other needs. Moving that half into a provider both inject, passing the value at the call, or turning one direction into an event removes the cycle instead of deferring it. There is nothing to wrap in a thunk, and no runtime resolution order to reason about.

Other things you will reach for and not find

Section titled “Other things you will reach for and not find”

Each is deliberate: the concept exists in NestJS to work around something Rust does not do.

NestJSWhy NestRS has none
configure(consumer) middleware, registerPreRequestHookThe word covers several shapes. Gating is a Guard, wrapping is an Interceptor, work around every request before the access decision is an interceptor declared #[interceptor(stage = unit)], body normalization is a Pipe, CORS and security headers are HttpConfig. Middleware maps every role to its home
@Global()What a seed or a factory makes is app-global — every config and connection, as TypeOrmModule.forRoot and ConfigModule.forRoot({ isGlobal: true }) are in NestJS. A provider a module lists is import-gated, and no flag opens it everywhere: the import list is its declaration, the one the boot-time access-graph check reads
app.enableShutdownHooks()Never opt-in. #[on_module_destroy] and #[on_application_shutdown] always run, best-effort, so one failing cleanup doesn’t skip the rest
Terminus’s gracefulShutdownTimeoutMs, Fastify’s return503OnClosingThe transport stops accepting at the signal and answers what it already took, so no request arrives to be answered 503; taking the replica out of rotation first is the platform’s — a Kubernetes preStop sleep, an ECS deregistration (leaving the load balancer first)
@Injectable() on everything#[injectable] marks a provider the container builds; a controller, resolver or gateway is already one through its own decorator

A guard, an interceptor, a pipe and an exception filter all read one UnitContext, as every NestJS enhancer reads one ExecutionContext, on every edge. The calls map one for one:

NestJSNestRS
ExecutionContextUnitContext, handed to every layer
context.getType()cx.edge() — Edge::Http, Edge::Graphql, Edge::Ws, Edge::Mcp, Edge::Queue, …
context.switchToHttp()cx.switch_to::<HttpView>(); in a guard, HttpView::of(cx)?
switchToWs(), GqlExecutionContext.create(context)cx.switch_to::<WsView>(), cx.switch_to::<GraphqlView>() — a view per edge
context.getHandler(), context.getClass()cx.handler() — the method and its host in one value
SetMetadata, Reflector.createDecorator#[meta(value)], typed, on a host or a method
reflector.get, reflector.getAllAndOverridecx.reflector().get::<M>() — the method’s value over its host’s
reflector.getAllAndMergecx.reflector().get_all::<M>()

What differs is where it reaches. The context is typed, so a value read by type cannot collide with another’s key, and the container is not on it: a layer injects what it needs, and the boot checks it. Execution context is the reference.

@Param('id'), @Query(), @Body(), @Req() have no counterpart, because the job they do is already done by the parameter’s type. A handler declares Path<Uuid>, Query<Filters> or Json<CreatePost>, and the extraction, the parse, the rules CreatePost declares and the 400 on malformed input come from that type — there is no ValidationPipe to register. The same applies to the request-scoped Scoped<T> and the guard-attached Ambient<T> — Extractors is the full list. A type never declares who may call: Authorized<Action, E> receives the row an #[authorize(Action, bind = Service)] beside it loaded, and only the attribute is the posture.

Interceptors follow the same move. There is no RxJS: intercept is an async fn receiving Next<'_>, and “after the handler” is the code you write after next.run(cx).await — no .pipe(map(...)), no stream to remember to subscribe.

A NestJS field is declared several times: on the entity, on the DTO, again with @ApiProperty() for Swagger, again with @Field() for GraphQL. Each copy is a chance to drift. NestRS declares it once — #[expose] on the SeaORM column — and derives the wire type, the create/update inputs, the JSON Schema behind GET /api-json, and the GraphQL object from that one site.

A column with no #[expose] reaches no transport at all, so the default is closed: adding a column to a table never widens the API by accident.

No runtime reflection, because nothing was erased

Section titled “No runtime reflection, because nothing was erased”

NestJS reads decorator metadata through reflect-metadata at runtime — the crutch exists because TypeScript types vanish at compile time, so the framework has to recover them from a side channel, and an interface can’t be injected without a hand-written token. NestRS decorators are attribute macros: they expand to plain Rust during compilation, and the types they read are the ones the compiler checks. There is no metadata registry to query at runtime, and no .env-driven reflection deciding what a decorator means — the environment moves values, every one of them, and never shape. What the macro emitted is what runs.

What ships is one executable. cargo build --release produces a binary you copy into a distroless image — no node_modules to install, no runtime to pin alongside it, no npm ci in the Dockerfile. The monorepo habits do carry over: a Cargo workspace is the layout you already run, apps/* next to shared crates, one lockfile at the root, local packages wired by path.