Module lifecycle

How a backend plugin is packaged, loaded, and torn down — @Module registration plus lifecycle hooks @OnInit, @OnAllModuleLoaded, and @OnUninstall.

IPlugin entry

backend/src/index.ts default-exports a class that implements IPlugin. It returns the root @Module class and metadata from module.metadata.json.

TSXbackend/src/index.ts

import type { IPlugin, PluginMetadata } from "@quan-erp/shared-types";
import metadata from "../module.metadata.json" with { type: "json" };
import { MyPluginModule } from "./my-plugin.module.js";

export default class MyPlugin implements IPlugin {
  getRootModule() { return MyPluginModule; }
  getName() { return metadata.name; }
  getVersion() { return metadata.pluginVersion; }
  getMetadata() { return metadata as PluginMetadata; }
}

Root @Module

Register providers, controllers, entities (plugin: "default"), and optional websocket handlers. Pair with @Cache on the same class for module-level cache. Lifecycle hooks usually live on this class (or on a @Service).

@Module({ name, providers, controllers, entities, websocket? })
@Cache(options) — in-memory or redis; must sit on the @Module class only

TSXmodule

import { Cache, Module } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { ChatWebsocket } from "./chat.websocket.js";
import { MyController } from "./my.controller.js";
import { MyEntity } from "./my.entity.js";
import { MyService } from "./my.service.js";

@Module({
  name: metadata.name,
  providers: [MyService],
  controllers: [MyController],
  entities: [{ plugin: "default", entities: [MyEntity] }],
  websocket: [ChatWebsocket],
})
@Cache({ type: "in-memory", checkperiod: 1000 })
export class MyPluginModule {}

Lifecycle annotations

Three hooks cover boot and teardown. Use property methods on the root @Module (or a DI-managed @Service). Constructor injection is not supported — inject dependencies with property @Inject / @InjectBuiltinLogger.

@OnInit() — this module (or service) is ready; safe for seed / local setup
@OnAllModuleLoaded() — every module finished @OnInit; safe for workers, cron listeners, cross-plugin calls
@OnUninstall() — plugin is being removed; disconnect queues, stop workers, cleanup resources

@OnInit

Runs once after the system has fully initialized the host module or service. Typical uses: default settings, COA/seed via DataSeedHistoryService, one-time local setup. Do not start cross-plugin workers here — use @OnAllModuleLoaded instead.

TSX@OnInit on module

import {
  ContainerRegistryManager,
  DataSeedHistoryService,
  Inject,
  InjectBuiltinLogger,
  Module,
  OnInit,
} from "@quan-erp/shared-backend-core";
import type { Loggable } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { MyService } from "./my.service.js";

@Module({
  name: metadata.name,
  providers: [MyService],
  controllers: [],
  entities: [],
})
export class MyPluginModule {
  @InjectBuiltinLogger()
  logger: Loggable;

  @Inject(DataSeedHistoryService, ContainerRegistryManager.BUILTIN_PLUGIN)
  dataSeedHistoryService: DataSeedHistoryService;

  @OnInit()
  async init() {
    const alreadySeeded = await this.dataSeedHistoryService.find(
      metadata.name,
      metadata.pluginVersion,
      "init",
    );
    if (alreadySeeded) {
      this.logger.log("Seeding skipped (already initialized)");
      return;
    }
    // … seed defaults …
    await this.dataSeedHistoryService.add({
      data: {
        pluginName: metadata.name,
        pluginVersion: metadata.pluginVersion,
        name: "init",
      },
    });
    this.logger.log("Module seeded successfully");
  }
}

TSX@OnInit on service

import { InjectBuiltinLogger, OnInit, Service } from "@quan-erp/shared-backend-core";
import type { Loggable } from "@quan-erp/shared-backend-core";

@Service()
export class CacheWarmupService {
  @InjectBuiltinLogger()
  logger: Loggable;

  @OnInit()
  async init() {
    this.logger.log("Warming local caches");
    // …
  }
}

@OnAllModuleLoaded

Runs once after every installed module has finished @OnInit. Use for background workers, CronJobService event listeners, or any work that needs other plugins’ services to be available.

TSX@OnAllModuleLoaded

import {
  ContainerRegistryManager,
  CronJobService,
  Inject,
  InjectBuiltinLogger,
  Module,
  OnAllModuleLoaded,
} from "@quan-erp/shared-backend-core";
import type { Loggable } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { MaturedSweepService } from "./matured-sweep.service.js";

@Module({
  name: metadata.name,
  providers: [MaturedSweepService],
  controllers: [],
  entities: [],
})
export class MyPluginModule {
  @InjectBuiltinLogger()
  logger: Loggable;

  @Inject(CronJobService, ContainerRegistryManager.BUILTIN_PLUGIN)
  cronJobService: CronJobService;

  @Inject(MaturedSweepService)
  sweep: MaturedSweepService;

  @OnAllModuleLoaded()
  async onAllModuleLoaded() {
    this.logger.log("All modules loaded — attaching cron listeners");
    this.cronJobService.addEventListener(
      metadata.name,
      "matured-sweep",
      () => this.sweep.run(),
    );
  }
}

@OnUninstall

Runs when the plugin is uninstalled from the system. Disconnect Redis/BullMQ workers, close sockets, and release other resources you started in @OnInit / @OnAllModuleLoaded.

TSX@OnUninstall

import {
  InjectBuiltinLogger,
  Module,
  OnUninstall,
} from "@quan-erp/shared-backend-core";
import type { Loggable } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { BackgroundWorker } from "./background.worker.js";

@Module({
  name: metadata.name,
  providers: [BackgroundWorker],
  controllers: [],
  entities: [],
})
export class MyPluginModule {
  @InjectBuiltinLogger()
  logger: Loggable;

  private worker = new BackgroundWorker();

  @OnUninstall()
  async cleanup() {
    this.logger.log("Uninstalling — stopping worker");
    await this.worker.disconnect();
  }
}

Boot & teardown order

01
Scan installed plugins
Only modules with installed=true load from installed-plugins.
02
Import module.js
Instantiate IPlugin and call getRootModule().
03
DI + entities
Wire services and sync tables.
04
@OnInit
Per-module (and service) init — seed and local setup.
05
@OnAllModuleLoaded
Cross-module hooks — workers, cron listeners.
06
@OnUninstall
When the plugin is removed — cleanup resources.

Build lifecycle

Use quan-erp watch <plugin> (or quan-erp watch in some repos) to compile backend + frontend into base/available-plugins/, then install from the ERP UI.

Module lifecycle

IPlugin entry

Root @Module

Lifecycle annotations

@OnInit

@OnAllModuleLoaded

@OnUninstall

Boot & teardown order

Scan installed plugins

Import module.js

DI + entities

@OnInit

@OnAllModuleLoaded

@OnUninstall

Build lifecycle