Export services

Publish backend services, entities, and types from a plugin so other plugins can install @quan-erp-plugins/<name>-backend and inject them with @Inject(Service, "plugin-name").

Overview

Backend cross-plugin reuse is a published package contract plus DI scoping. Export stable classes from backend/src/export.ts, build and publish @quan-erp-plugins/<name>-backend, then consumers install the package and inject with the provider plugin’s metadata.name.

Never import another plugin’s backend/src/ directly — only the published package
Package name: @quan-erp-plugins/<plugin-folder>-backend
DI scope: @Inject(ServiceClass, "provider-plugin-name") — second arg matches module.metadata.json name
Declare pluginDependencies so the provider loads before the consumer

overview

export → publish → inject

Provider plugin

Implement @Service / entities
Re-export from backend/src/export.ts
npm run build:export
npm run release:beta
@quan-erp-plugins/name-backend

Consumer plugin

npm install @quan-erp-plugins/name-backend
pluginDependencies in metadata
@Inject(Service, "name")

export.ts→

build:export→

publish→

@Inject

Export public classes → publish the backend package → consumers inject with the provider plugin name.

1. Define the public surface (export.ts)

Create or update backend/src/export.ts. Everything re-exported here becomes the public API other plugins may depend on. Export only stable services, selected entities/DTOs, and types — not internal helpers or WIP modules.

Use .js extensions in relative re-exports (ESM build)
Prefer exporting @Service classes consumers will inject
Entity exports are optional — only when another plugin must type against them
Keep export.ts small; deep paths stay private

TSXbackend/src/export.ts

// plugins/fleet-management/backend/src/export.ts

export * from "./feature/driver/driver.service.js";
export * from "./feature/driver/driver.controller.js";
export * from "./schema/driver/driver.entity.js";

2. Build and publish

The plugin backend package.json ships scripts that Rollup-compile export.ts into dist/ and publish under @quan-erp-plugins/.

build:export — compile export.ts + dependencies into dist/
release:beta — publish to the internal / self-hosted npm registry with the beta tag
Align @quan-erp/* versions with the base stack before publishing
Consumers need a valid ~/.npmrc for the same registry

SHTerminal (provider plugin backend/)

cd plugins/fleet-management/backend
npm run build:export
npm run release:beta

3. Consumer — install the package

In the consumer plugin’s backend package, install only what you need. For backend services, install the -backend package (you do not need the frontend package).

Add the dependency to plugins/<consumer>/backend/package.json
Pin a compatible version range that matches what you tested
Do not copy service source files into the consumer plugin

SHTerminal (consumer plugin backend/)

cd plugins/my-plugin/backend
npm install @quan-erp-plugins/fleet-management-backend

4. Consumer — inject with plugin scope

Use @Inject with the provider plugin’s metadata.name as the second argument so DI resolves outside the current module scope.

Second argument MUST equal the provider’s module.metadata.json "name" (e.g. "fleet-management")
Omit the second argument only for services registered in the same plugin
Builtin platform services use ContainerRegistryManager.BUILTIN_PLUGIN instead of a plugin name
Call cross-plugin work from @OnAllModuleLoaded when you need every dependency module finished @OnInit

TSXconsumer service

import { Service, Inject } from "@quan-erp/shared-backend-core";
import { FleetDriverManagementService } from "@quan-erp-plugins/fleet-management-backend";

@Service()
export class MyService {
  @Inject(FleetDriverManagementService, "fleet-management")
  driverService: FleetDriverManagementService;

  async doSomething() {
    const drivers = await this.driverService.list();
    return drivers;
  }
}

5. Declare pluginDependencies

The consumer must list the provider in module.metadata.json so the host loads the provider first and refuses to start if it is missing or incompatible.

Keys are provider plugin names (folder / metadata.name), not npm package names
Values are semver ranges for the provider’s pluginVersion
Without this entry, DI may fail or load order may be wrong

JSONplugins/my-plugin/module.metadata.json

{
  "name": "my-plugin",
  "type": "",
  "pluginVersion": "1.0.0",
  "description": "Depends on fleet-management backend APIs",
  "moduleEntryObject": "Module",
  "requiredBasedVersion": "1.0.0",
  "pluginDependencies": {
    "fleet-management": "^1.0.0"
  }
}

Checklist

Provider: backend/src/export.ts re-exports public services / types
Provider: npm run build:export && npm run release:beta (or your registry publish flow)
Consumer: npm install @quan-erp-plugins/<name>-backend
Consumer: pluginDependencies includes the provider name + version range
Consumer: @Inject(Service, "<provider-metadata-name>")
Both plugins installed in the ERP and on a matching @quan-erp/* version line

Common failures

Importing plugins/<other>/backend/src — breaks packaging and load order; use the published package
Wrong @Inject plugin name — must match metadata.name, not the npm package name
Missing pluginDependencies — provider may load after consumer or be absent
Forgot build:export / publish — consumer installs an empty or stale package
Version skew — provider package and installed pluginVersion out of sync with requiredBasedVersion
Using the service before @OnAllModuleLoaded when the call needs every module initialized