Providers and services in nestrs

Providers are the services, repositories, and utilities that your application logic depends on. In nestrs, any type can become a provider by implementing the Injectable trait — the #[injectable] proc-macro generates that implementation for you. The framework constructs and caches providers in the ProviderRegistry, then makes them available to controllers and other providers through Axum’s State extractor.

Marking a type as injectable

Apply #[injectable] to a struct to generate the Injectable trait implementation. nestrs calls construct to build the type, injecting any dependencies it finds in the registry:

use nestrs::prelude::*;
use std::sync::Arc;

#[injectable]
pub struct AppService {
    prisma: Arc<PrismaService>,
}

nestrs infers dependencies from the struct fields. Any field of type Arc<T> where T is a registered provider is resolved from the registry automatically.

construct is synchronous. Do not call block_on or perform I/O inside it — use on_module_init for async setup.

Provider scopes

Control how long a provider instance lives with the scope argument:

// Default: one shared instance per application
#[injectable]
pub struct SingletonService;

// New instance on every injection site / registry.get() call
#[injectable(scope = "transient")]
pub struct TransientService;

// One instance per HTTP request (requires use_request_scope())
#[injectable(scope = "request")]
pub struct RequestScopedService;

Scope	Lifetime	NestJS equivalent
`"singleton"` (default)	One per application container	`Scope.DEFAULT`
`"transient"`	New instance per resolution	`Scope.TRANSIENT`
`"request"`	One per HTTP request	`Scope.REQUEST`

Registering providers in a module

List your providers in the providers field of the enclosing module. Providers that other modules need must also appear in exports:

#[module(
    controllers = [AppController, AppControllerV2],
    providers   = [AppService],
)]
pub struct AppModule;

To share a provider across modules:

#[module(
    controllers = [UserController],
    providers   = [UserService],
    exports     = [UserService],
)]
pub struct UserModule;

#[module(
    imports  = [UserModule],
    providers = [AppService],
)]
pub struct AppModule;

Injecting providers into controllers

Controllers access their providers via Axum’s State extractor. The #[routes(state = T)] macro wires the service type into the router, and handler functions can take service: Arc<T> directly:

#[routes(state = AppService)]
impl AppController {
    #[get("/")]
    pub async fn root(service: Arc<AppService>) -> &'static str {
        service.get_hello()
    }

    #[get("/db-health")]
    pub async fn db_health(
        service: Arc<AppService>,
    ) -> Json<DbHealthResponse> {
        Json(service.db_health().await)
    }
}

Multiple providers per controller (tuple state)

If a controller needs multiple services, specify a tuple in state:

#[routes(state = (AppService, UserService))]
impl AppController {
    #[get("/profile")]
    pub async fn profile(
        app: Arc<AppService>,
        users: Arc<UserService>,
    ) -> Json<UserProfile> {
        Json(users.get_profile(app.default_tenant()).await)
    }
}

nestrs stitches the composite state from the ProviderRegistry via RouteStateFromRegistry. Handlers only receive the services they declare. Explicit State(service): State<Arc<T>> remains supported as well.

Injecting providers into other providers

When one provider depends on another, declare the dependency as an Arc<T> field and ensure both types are registered in the same module (or that the dependency is exported from an imported module):

#[injectable]
pub struct AppService {
    prisma: Arc<PrismaService>,
}

impl AppService {
    pub async fn list_users(&self) -> Result<Vec<UserRow>, String> {
        self.prisma
            .query_all_as(r#"SELECT "id", "email", "name" FROM "User""#)
            .await
    }
}

Lifecycle hooks

Injectable provides five async hooks (all default to no-ops): on_module_init, on_application_bootstrap, on_before_application_shutdown, on_application_shutdown, and on_module_destroy.

use nestrs::prelude::*;
use async_trait::async_trait;

#[injectable]
pub struct DatabaseService {
    // fields ...
}

#[async_trait]
impl Injectable for DatabaseService {
    fn construct(registry: &ProviderRegistry) -> Arc<Self> {
        Arc::new(Self { /* wire fields */ })
    }

    async fn on_module_init(&self) {
        // Run after all singletons are constructed; safe to do async I/O here.
    }

    async fn on_before_application_shutdown(&self) {
        // NestJS `beforeApplicationShutdown`: flush caches while dependents are still alive.
    }

    async fn on_application_shutdown(&self) {
        // Close connections, flush buffers.
    }
}

On startup, listen() first eagerly constructs all singleton providers (in registration order), then runs on_module_init across all singletons, then on_application_bootstrap, and only then binds the listener — hooks run before the server accepts traffic. Within each hook phase, providers run in dependency order (construction dependencies first, ties broken by registration order). On graceful shutdown the phases run in reverse: on_before_application_shutdown → on_application_shutdown → on_module_destroy, each in reverse initialization order so dependencies are torn down after their dependents.

Lifecycle hooks only run for singleton providers. Transient providers are constructed on demand and do not receive hook calls.

Custom factory providers

Use register_use_factory when construction order must be explicit or when you need to close a provider dependency cycle without calling registry.get() eagerly inside another type’s construct:

use nestrs::core::{ProviderRegistry, ProviderScope};
use std::sync::Arc;

fn register_heavy(registry: &mut ProviderRegistry) {
    registry.register_use_factory::<HeavyService>(ProviderScope::Singleton, |reg| {
        let light = reg.get::<LightService>();
        Arc::new(HeavyService::new(light))
    });
}

All custom provider variants

Method	NestJS analogue	Notes
`register_use_value::<T>(Arc<T>)`	`useValue`	Pre-built singleton; lifecycle hooks are not run — any `T` is accepted, so there is no hook impl to call
`register_use_value_with_lifecycle::<T>(Arc<T>)`	`useValue` + `OnModuleInit` & friends	Requires `T: ProviderLifecycle`; the framework drives `T`’s five hooks like an `Injectable`
`register_use_factory::<T>(scope, \|reg\| Arc<T>)`	`useFactory`	Sync closure; call `reg.get()` for dependencies; lifecycle hooks are not run
`register_use_factory_with_lifecycle::<T>(scope, \|reg\| Arc<T>)`	`useFactory` + lifecycle	Requires `T: ProviderLifecycle`; hooks run while `T` is singleton-scoped
`register_use_class::<T>()`	`useClass`	Same as `register::<T>()` for normal `#[injectable]` types

Keep factory closures non-async. Defer I/O to on_module_init on the produced type (which requires a hook-driving registration — the *_with_lifecycle variants, or a plain #[injectable] type registered with register), or to ConfigurableModuleBuilder::for_root_async for module-level configuration.

Get Started

Core Concepts

API Development

Security & Auth

Transports & Protocols

Operations

Providers and services in nestrs

Marking a type as injectable

Provider scopes

Registering providers in a module

Injecting providers into controllers

Multiple providers per controller (tuple state)

Injecting providers into other providers

Lifecycle hooks

Custom factory providers

All custom provider variants

​Marking a type as injectable

​Provider scopes

​Registering providers in a module

​Injecting providers into controllers

​Multiple providers per controller (tuple state)

​Injecting providers into other providers

​Lifecycle hooks

​Custom factory providers

​All custom provider variants

Marking a type as injectable

Provider scopes

Registering providers in a module

Injecting providers into controllers

Multiple providers per controller (tuple state)

Injecting providers into other providers

Lifecycle hooks

Custom factory providers

All custom provider variants