Skip to content

Modules

waku modularity system is heavily inspired by the NestJS and Tramvai frameworks.

The concept of modularity is well-explained with examples in the NestJS documentation.

Module

A module is a class annotated with the @module() decorator. This decorator attaches metadata to the class, which waku uses to construct the application graph.

Every waku application has at least one module: the root module, also known as the composition root. This module serves as the starting point for waku to build the entire application graph.

Parameter Description
providers List of providers for dependency injection
imports List of modules imported by this module
exports List of types or modules exported by this module
extensions List of module extensions for lifecycle hooks
is_global Whether this module is global or not

The module encapsulates providers by default, meaning you can only inject providers that are either part of the current module or explicitly exported from other imported modules. The exported providers from a module essentially serve as the module's public interface or API.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
from waku import module
from waku.di import Scoped

from app.modules.config.module import ConfigModule


class UsersService:
    pass


@module(
    providers=[Scoped(UsersService)],  # Register the service with a scoped lifetime
    imports=[ConfigModule],  # Import another module
    exports=[UsersService],  # Expose the service to other modules
)
class UsersModule:
    pass


@module(imports=[UsersModule])  # Root module importing UsersModule
class AppModule:
    pass

Note

Encapsulation is enforced by validators, which you can disable at runtime if needed. However, disabling them entirely is not recommended, as they help maintain modularity.

Module Re-exporting

You can re-export a module by including it in the exports list of another module. This is useful for exposing a module’s providers to other modules that import the re-exporting module.

1
2
3
4
5
6
@module(
    imports=[UsersModule],
    exports=[UsersModule],
)
class IAMModule:
    pass

Global modules

If you need to import the same set of modules across your application, you can mark a module as global. Once a module is global, its providers can be injected anywhere in the application without requiring explicit imports in every module.

To make a module global, set the is_global param to True in the @module() decorator.

Note

Root module are always global.

Warning

Global modules are not recommended for large applications, as they can lead to tight coupling and make the application harder to maintain.

1
2
3
4
5
6
from waku import module


@module(is_global=True)
class UsersModule:
    pass

Dynamic Module

Dynamic modules allow you to create modules dynamically based on conditions, such as the runtime environment of your application.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
from waku import DynamicModule, module
from waku.di import Scoped


class ConfigService:
    pass


class DevConfigService(ConfigService):
    pass


class DefaultConfigService(ConfigService):
    pass


@module()
class ConfigModule:
    @classmethod
    def register(cls, env: str = 'dev') -> DynamicModule:
        # Choose the config provider based on the environment
        config_provider = DevConfigService if env == 'dev' else DefaultConfigService
        return DynamicModule(
            parent_module=cls,
            providers=[Scoped(config_provider, type_=ConfigService)],  # Register with interface type
        )

And then you can use it in any of your modules or in the root module:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from waku import module

from app.modules.config.module import ConfigModule


@module(
    imports=[
        ConfigModule.register(env='dev'),
    ],
)
class AppModule:
    pass

You can also make a dynamic module global by setting is_global=True in the DynamicModule constructor.

Note

While you can use any method name instead of register, we recommend sticking with register for consistency.