alepha@docs:~/docs/reference/primitives$
cat $module.md | pretty
2 min read

#$module

#Import

typescript 
1import { $module } from "alepha";

#Overview

Wrap Services and Primitives into a Module.

  • A module is just a Service with some extra {@link Module}.
  • You must attach a name to it.
  • Name must follow the pattern: project.module.submodule. (e.g. myapp.users.auth).

#Options

Option Type Required Description
name string Yes Name of the module
services Array<Service> No Services that belong to this module
variants Array<Service> No Alternative implementations that belong to this module but are NOT auto-injected
imports Array<Service<Module>> No Other modules this module depends on
primitives Array<PrimitiveFactoryLike> No List of $primitives to register in the module.
register Object No Additive side-effect hook
atoms Array<Atom<any>> No List of atoms to register in the module.

#Examples

ts 
1import { $module } from "alepha";2import { MyService } from "./MyService.ts";3 4export default $module({5 name: "my.project.module",6 services: [MyService],7});

#Slots

  • services[] — always auto-injected. Module metadata attached.
  • variants[] — module metadata attached but NOT auto-injected. Two typical uses: (1) alternative implementations picked at register-time via alepha.with({ provide, use }); (2) services whose instantiation is driven externally (e.g., the framework core).
  • imports[] — other modules this one depends on. Wired before register() runs.
  • atoms[] — registered on the store.
  • primitives[] — tagged with module metadata.
  • register(alepha) — purely additive side-effect hook. Runs AFTER imports[] are wired and BEFORE services[] are auto-injected — so substitutions it records (e.g. alepha.with({ provide, use })) apply to the subsequent auto-injection. It can never suppress auto-registration.

#Why Modules?

#Logging

By default, AlephaLogger will log the module name in the logs. This helps to identify where the logs are coming from.

You can also set different log levels for different modules.

#Modulith

Force to structure your application in modules, even if it's a single deployable unit. It helps to keep a clean architecture and avoid monolithic applications.

#When not to use Modules?

Small applications do not need modules. Modules earn their keep when the application grows — as a rule of thumb, once a module has 30+ $actions, consider splitting it.