Packages
Every opt-in crate the NestRS framework ships — grouped by concern, with Cargo names, umbrella features, and links to the docs.
NestRS installs as one dependency. Each concern — HTTP, GraphQL, queues, authorization, observability — is a Cargo feature you enable when the binary needs it, and a feature you leave off is code you never compile. A headless worker compiles no HTTP stack; an MCP-only assistant compiles no GraphQL schema.
cargo add nest-rs --features http,seaorm,graphqlUndecided? --features full turns on every capability but testing, which is a dev
dependency — narrow it later without
moving a single use. Either way nest_rs::prelude::* covers the decorators
and types an app reaches for daily.
The table below is a menu of features, not a list of crates to line up.
Umbrella
Section titled “Umbrella”| Crate | Cargo feature | What it is | Docs |
|---|---|---|---|
nest-rs | (always) | Re-exports core + optional surface crates; nest_rs::prelude for the common case. One version to bump, and the only framework line your manifest needs — a decorator’s expansion resolves through it | Getting started |
nest-rs-core | (via umbrella) | DI container, #[module], lifecycle hooks, boot-time access graph, and the one pipeline every unit runs through — Interceptor, ExceptionFilter, #[interceptor] | Fundamentals |
Default features: http, config — every other surface crate is opt-in via
features = [...].
Transports
Section titled “Transports”An adapter brings the transport its host serves on, so an app imports the adapter and
names the transport only to pin it. HTTP-shaped surfaces
(GraphQL, OpenAPI, MCP, WebSocket gateways) mount on the same
HttpTransport — one port, one TLS config.
| Crate | Cargo feature | What it is | Docs |
|---|---|---|---|
nest-rs-http | http | HTTP transport — controllers, routes, extractors, on the http crate’s types | HTTP |
nest-rs-graphql | graphql | Resolver discovery, schema composition, async-graphql integration | GraphQL |
nest-rs-ws | ws | WebSocket gateways — self-mount on the HTTP transport | WebSockets |
nest-rs-openapi | openapi | OpenAPI 3 document + bundled Swagger UI from the route table | OpenAPI |
nest-rs-static-files | static-files | A built front end and public files, from a directory or embedded, as the router’s fallback | Static files |
nest-rs-mcp | mcp | Model Context Protocol server over HTTP | MCP |
| Crate | Cargo feature | What it is | Docs |
|---|---|---|---|
nest-rs-database | database | The unit-of-work port every edge runs through — UnitOfWork, run_unit and the ambient executor any driver implements | Database · Writing a driver |
nest-rs-seaorm | seaorm | First-class SeaORM integration — SeaOrmDatabaseModule, Repo, transactions, dataloaders, and #[expose]: one entity declaration for GraphQL + OpenAPI + CRUD | Database · CRUD · Relations |
nest-rs-storage | storage | Object storage whose URL picks the backend, s3:// or memory:/// — injectable Storage, presigned URLs, via object_store | Storage |
Security
Section titled “Security”Authentication answers who; authorization answers what they may do.
Product-specific strategies and policies live in your features crate —
these crates are the engine.
| Crate | Cargo feature | What it is | Docs |
|---|---|---|---|
nest-rs-authn | authn | JWT service, pluggable Strategy, AuthnGuard | Authentication |
nest-rs-authz | authz | Ability-based authorization — access gate, row-level filter, response masking | Authorization |
nest-rs-oauth-server | oauth-server | The OAuth 2.0 authorization server role — RFC 6749 §2.3 client authentication through a guard, §4.4.2 token request, §5.1 access token response, §5.2 token-endpoint errors; brings authn, whose Strategy the guard runs | Split deployment |
nest-rs-oauth-client | oauth-client | The OAuth 2.0 client role — Authorization Code flow with PKCE against someone else’s authorization server | OAuth 2.0 |
nest-rs-oauth-resource | oauth-resource | RFC 9728 protected-resource metadata — the well-known document, and the 401 challenge pointer | Split deployment |
nest-rs-social | social | Open SocialProvider contract — first-party GitHub/Google, third-party providers via the same seam | Social login |
Request pipeline
Section titled “Request pipeline”Cross-cutting layers, each bound app-wide by the module the app boots
(GlobalGuards<(…)>, GlobalPipes<(…)>) or per host and
method. A guard gates a caller, so it runs on the edges that have one — HTTP,
GraphQL, WebSockets and MCP. A pipe validates what a unit carries: on an
argument on every edge, a job’s payload included, and through #[use_pipes]
on an HTTP or WebSocket host and method. A global pipe runs over a route’s
JSON body, a /graphql operation’s variables and a WebSocket message’s data,
and nothing else: an MCP tool’s arguments and a job’s payload take a pipe on
the argument.
| Crate | Cargo feature | What it is | Docs |
|---|---|---|---|
nest-rs-guards | guards | The Guard trait — gates access before the handler runs | Guards |
nest-rs-pipes | pipes | Stateless input validation and transformation at the edge | Pipes |
Interceptors and exception filters take no feature: Interceptor,
ExceptionFilter and #[interceptor] live in nest_rs::core, beside the
pipeline that runs them, and run on every edge — around a job, a tick and an
event as around a request. See Interceptors and
Exception filters.
Background work
Section titled “Background work”| Crate | Cargo feature | What it is | Docs |
|---|---|---|---|
nest-rs-queue | queue | Backend-agnostic job contract, #[process] registry and the QueueWorker that runs it | Queue |
nest-rs-redis | redis, redis-queue, redis-throttler, redis-schedule | The Redis connection (redis), one per instance, and a feature per binding over it — the queue on Redis Streams, the rate-limit store, the schedule’s occurrence lock | Queue wiring |
nest-rs-schedule | schedule | Cron-style scheduled jobs — #[scheduled] + ScheduleModule | Schedule |
nest-rs-events | events | Typed in-process event bus — #[listeners] / #[on_event] | Events |
Platform
Section titled “Platform”| Crate | Cargo feature | What it is | Docs |
|---|---|---|---|
nest-rs-config | config | Namespaced env + file config bound to typed #[config] structs | Configuration |
nest-rs-health | health | Kubernetes-style liveness / readiness / startup probes | Health |
nest-rs-throttler | throttler | Per-route rate limiting via ThrottlerGuard | Throttler |
nest-rs-opentelemetry | opentelemetry | Logs, traces, metrics, W3C propagation, OTLP export | OpenTelemetry |
nest-rs-server-timing | server-timing | W3C Server-Timing response header (independent of OTel) | Server-Timing |
Developer tools
Section titled “Developer tools”| Crate | Cargo feature | What it is | Docs |
|---|---|---|---|
nest-rs-cli | (binary: nestrs) | Scaffold workspaces, generate features, project health checks | CLI |
nest-rs-testing | testing | In-process harness — boot the real DI graph headless (HeadlessApp), drive HTTP/GraphQL/MCP without a socket beside http (TestApp), issue TLS test certificates (TestAuthority); beside queue it carries queue_kit!, the behaviour a queue driver runs against its backend | Testing · Binding a queue driver |
Typical binary profiles
Section titled “Typical binary profiles”These are composition patterns, not separate crates — they show which packages a deployable usually pulls in.
| Binary role | Packages you typically import |
|---|---|
| REST + OpenAPI API | http, openapi, config, seaorm, authn, authz, health |
| GraphQL API | http, graphql, config, seaorm, authn, authz |
| WebSocket live service | http, ws, config, seaorm, authn, authz |
| Queue worker | redis-queue, schedule, seaorm, config |
| MCP assistant | http, mcp, config, authn, authz, oauth-resource |
| Token issuer | http, config, seaorm, authn, oauth-server |
See The Publish workspace for five real apps that follow these profiles.
Not listed here
Section titled “Not listed here”Internal macro crates (nest-rs-*-macros) implement the decorators — you
never add them as direct dependencies; the surface crate re-exports what you
need. nest-rs-codegen holds the token helpers they share. A decorator
crate of your own, a proc-macro crate, is the one place it is a dependency:
it uses the crate’s root items, the kit semver covers, and the rest is the
framework’s — Writing a decorator walks it.
For a decorator index see Decorators.
Your product’s features crate holds domain modules (entities, services,
controllers per transport). It is workspace-local and not published to
crates.io — copy crates/features/src/users/
as the exemplar.
Adding a capability to your app
Section titled “Adding a capability to your app”Turn on its feature. There is one framework line, and adding a transport never adds a second — an app serving REST, GraphQL, the database and authz names it once:
[dependencies]nest-rs = { workspace = true, features = [ "http", "config", "seaorm", "graphql", "openapi", "authn", "authz", "health",] }In a fresh project the same step is
cargo add nest-rs --features <capability> — exactly what each module’s
adoption page shows. Then import the matching modules — SeaOrmDatabaseModule
in the app’s root, for example; a controller or a resolver brings HttpModule or
GraphqlModule itself, and the adapter binding a guard imports the module providing
it. The Publish workspace and
Getting started walk through a full composition.
Why one entry is enough
Section titled “Why one entry is enough”A decorator is a procedural macro, and its expansion resolves paths against
your crate’s extern prelude. NestRS decorators root theirs at
::nest_rs::<concern>::…, which that single entry reaches — so the feature list
is the install. Nothing a decorator expands into is a line you write.
Get the dependency wrong and the compiler says so in your own terms:
error: this nestrs decorator expands into the framework, which this crate cannot reach. Add to Cargo.toml:The message does not stop there — it ends on the complete nest-rs = { … }
line to paste, carrying the version the decorator that failed to resolve was
built from and the features it needs. That line is elided here on purpose:
printed by the compiler it is always current, and written on this page it
would go stale at the next release.
Get the feature wrong — the likelier mistake, since the dependency is
already there — and the diagnostic is rustc’s own. A missing feature reads as a
missing item, with a note telling you which:
error[E0433]: failed to resolve: could not find `seaorm` in `nest_rs` | = note: found an item that was configured out = note: the item is gated behind the `seaorm` featureAdd the feature named in the note to the nest-rs line — never a second crate.
A feature an attribute pulls into a decorator’s expansion — authz for
#[authorize], seaorm and authz for #[crud] — is named by the decorator
itself, before rustc’s own errors, in one message naming every feature the
attribute you wrote needs and ending on the line to paste, its version elided
here for the same reason:
error: `#[authorize]` expands into `nest_rs::authz`, which this build does not enable. Add the feature to Cargo.toml:
nest-rs = { version = "…", features = ["authz"] }The nest-rs-* crates stay published and keep their names — they are separate
compilation units, which is what makes an unused capability free. They are not
the entry point, and renaming the nest-rs dependency is unsupported: the same
limit tokio has, for the same reason.
What stays in your manifest
Section titled “What stays in your manifest”Crates your own code names. A job payload deriving serde::Serialize, an
indicator returning anyhow::Result, an entity written against sea-orm — those
are yours, and hiding them behind a re-export would cost you their feature flags
and a truthful cargo tree. No Rust framework hides them; NestRS does not
either. Name each at a requirement compatible with the framework’s: the
libraries NestRS’s own API is written in keep one major for the whole 7.x line
(Third-party libraries).
GraphQL used to be the one exception, and no longer is: #[operations] wraps
async-graphql’s #[Object], but it now pins that expansion to the framework’s
own re-export, so nest-rs --features graphql alone compiles a resolver.
async-graphql returns to the rule above — yours when your code names it,
which for its types you can avoid entirely with
use nest_rs::graphql::async_graphql::{Context, Result};, and for its derives
you cannot, exactly as for serde.
Going further
Section titled “Going further”- Getting started — scaffold an app and write the first route.
- The Publish workspace — five apps that follow these binary profiles.
- Fundamentals — the DI container every capability wires into.