scripts/backend-module/backend-module-guide.md
A backend module is a self-contained unit of backend functionality tied to a specific n8n feature.
Benefits of modularity:
To set up a backend module, run this command at monorepo root:
pnpm setup-backend-module
Your new module will be located at packages/cli/src/modules/my-feature. Rename my-feature in the dirname and in the filenames to your actual feature name. Use kebab-case.
A module’s file structure is as follows:
.
├── __tests__
│ ├── my-feature.controller.test.ts
│ └── my-feature.service.test.ts
├── my-feature.entity.ts # DB model
├── my-feature.repository.ts # DB access
├── my-feature.config.ts # env vars
├── my-feature.constants.ts # constants
├── my-feature.controller.ts # HTTP REST routes
├── my-feature.service.ts # business logic
└── my-feature.module.ts # entrypoint
This is only a template - your module may not need all of these files, or it may need more than these and also subdirs to keep things organized. Infixes are currently not required (except for the .module.ts entrypoint), but infixes are strongly recommended as they make the contents searchable and discoverable.
Backend modules currently live at packages/cli/src/modules, so imports can be:
@n8n/db, @n8n/backend-common, @n8n/backend-test-utils, etc.clicliModules are managed via env vars:
N8N_ENABLED_MODULES.N8N_DISABLED_MODULES.Modules that are under a license flag are automatically skipped on startup if the instance is not licensed to use the feature.
The .module.ts file is the entrypoint of the module and uses the @BackendModule() decorator:
@BackendModule({ name: 'my-feature' })
export class MyFeatureModule implements ModuleInterface {
async init() {
await import('./my-feature.controller');
const { MyFeatureService } = await import('./my-feature.service');
Container.get(MyFeatureService).start();
}
@OnShutdown()
async shutdown() {
const { MyFeatureService } = await import('./my-feature.service');
await Container.get(MyFeatureService).shutdown();
}
async entities() {
const { MyEntity } = await import('./my-feature.entity.ts');
return [MyEntity]
}
async settings() {
const { MyFeatureService } = await import('./my-feature.service');
return Container.get(MyFeatureService).settings();
}
async context() {
const { MyFeatureService } = await import('./my-feature.service');
return { myFeatureProxy: Container.get(MyFeatureService) };
}
}
The entrypoint is responsible for providing:
typeorm, e.g. in insights, the three database entities InsightsMetadata, InsightsByPeriod and InsightsRaw{ summary: true, dashboard: false }WorkflowExecuteAdditionalData. This allows you to make module functionality available to core, namespaced under the module name. For now, you will also need to manually update the type of WorkflowExecuteAdditionalData to reflect the resulting context.A module entrypoint may or may not need to implement all of these methods.
Why do we use dynamic imports in entrypoint methods? await import('...') ensures we load module-specific logic only when needed, so that n8n instances which do not have a module enabled, or do not have licensed access to it, do not pay for the performance cost. Linting enforces that relative imports in the entrypoint use dynamic imports. Loading on demand is also the reason why the entrypoint does not use dependency injection, and forbids it via linting.
A module may be fully behind a license flag:
@BackendModule({
name: 'external-secrets',
licenseFlag: 'feat:externalSecrets'
})
export class ExternalSecretsModule implements ModuleInterface {
// This module will be activated only if the license flag is true.
}
A module may be restricted to specific instance types:
@BackendModule({
name: 'my-feature',
instanceTypes: ['main', 'webhook']
})
export class MyFeatureModule implements ModuleInterface {
// This module will only be initialized on main and webhook instances,
// not on worker instances.
}
If instanceTypes is omitted, the module will be initialized on all instance types (main, webhook, and worker).
If a module is only partially behind a license flag, e.g. insights, then use the @Licensed() decorator instead:
class InsightsController {
constructor(private readonly insightsService: InsightsService) {}
@Get('/by-workflow')
@Licensed('feat:insights:viewDashboard')
async getInsightsByWorkflow(
_req: AuthenticatedRequest,
_res: Response,
@Query payload: ListInsightsWorkflowQueryDto,
) {
const dateRangeAndMaxAgeInDays = this.getMaxAgeInDaysAndGranularity({
dateRange: payload.dateRange ?? 'week',
});
return await this.insightsService.getInsightsByWorkflow({
maxAgeInDays: dateRangeAndMaxAgeInDays.maxAgeInDays,
skip: payload.skip,
take: payload.take,
sortBy: payload.sortBy,
});
}
}
Module-level decorators to be aware of:
@OnShutdown() to register a method to be called during the instance shutdown sequenceTo register a controller with the server, simply import the controller file in the module entrypoint:
@BackendModule({ name: 'my-feature' })
export class MyFeatureModule implements ModuleInterface {
async init() {
await import('./my-feature.controller');
}
}
A controller must handle only request-response orchestration, delegating business logic to services.
@RestController('/my-feature')
export class MyFeatureController {
constructor(private readonly myFeatureService: MyFeatureService) {}
@Get('/summary')
async getSummary(_req: AuthenticatedRequest, _res: Response) {
return await this.myFeatureService.getSummary();
}
}
Controller-level decorators to be aware of:
@RestController() to define a REST controller@Get(), @Post(), @Put(), etc. to define controller routes@Query(), @Body(), etc. to validate requests@GlobalScope() to gate a method depending on a user's instance-wide permissions@ProjectScope() to gate a method depending on a user's project-specific permissions@Licensed() to gate a method depending on license stateServices handle business logic, delegating database access to repositories.
To kickstart a service during module init, run the relevant method in the module entrypoint:
@BackendModule({ name: 'my-feature' })
export class MyFeatureModule implements ModuleInterface {
async init() {
const { MyFeatureService } = await import('./my-feature.service');
Container.get(MyFeatureService).start();
}
}
A module typically has one service, but it may have as many as needed.
@Service()
export class MyFeatureService {
private intervalId?: NodeJS.Timeout;
constructor(
private readonly myFeatureRepository: MyFeatureRepository,
private readonly logger: Logger,
private readonly config: MyFeatureConfig,
) {
this.logger = this.logger.scoped('my-feature');
}
start() {
this.logger.debug('Starting feature work...');
this.intervalId = setInterval(
() => {
this.logger.debug('Running scheduled task...');
},
this.config.taskInterval * 60 * 1000,
);
}
Service-level decorators to be aware of:
@Service() to make a service usable by the dependency injection container@OnLifecycleEvent() to register a class method to be called on an execution lifecycle event, e.g. nodeExecuteBefore, nodeExecuteAfter, workflowExecuteBefore, and workflowExecuteAfter@OnPubSubEvent() to register a class method to be called on receiving a message via Redis pubsub@OnLeaderTakeover() and @OnLeaderStepdown to register a class method to be called on leadership transition in a multi-main setupRepositories handle database access using typeorm, operating on database models ("entities").
@Service()
export class MyFeatureRepository extends Repository<MyFeatureEntity> {
constructor(dataSource: DataSource) {
super(MyFeatureEntity, dataSource.manager);
}
async getSummary() {
return await /* typeorm query on entities */;
}
}
Repository-level decorators to be aware of:
@Service() to make a repository usable by the dependency injection containerEntities are database models, typically representing tables in the database.
@Entity()
export class MyFeatureEntity extends BaseEntity {
@Column()
name: string;
@Column()
count: number;
}
We recommend using the .entity.ts infix, but omit the -Entity suffix from the class name to make it less verbose. (The -Entity suffix is being used in the setup example only for consistency with other placeholders.)
Entities must be registered with typeorm in the module entrypoint:
class MyFeatureModule implements ModuleInterface {
async entities() {
const { MyFeatureEntity } = await import('./my-feature.entity');
return [MyFeatureEntity];
}
}
Entity-level decorators to be aware of:
@Entity() to define an entityAs an exception, migrations remain centralized at @n8n/db/src/migrations, because conditionally running migrations would introduce unwanted complexity at this time. This means that schema changes from modules are always applied to the database, even when modules are disabled.
Module-specific configuration is defined in the the .config.ts file:
@Config
export class MyFeatureConfig {
/**
* How often in minutes to run some task.
* @default 30
*/
@Env('N8N_MY_FEATURE_TASK_INTERVAL')
taskInterval: number = 30;
}
Config-level decorators to be aware of:
@Env() to define environment variables@Config() to register a config class and make it usable by the dependency injection containerOccasionally, a module may need to define a module-specific CLI command. To do so, set up a .command.ts file and use the @Command() decorator. Currently there are no module-specific commands, so use any of the existing global CLI commands at packages/cli/src/commands as reference.
Place unit and integration tests for a backend module at packages/cli/src/modules/{featureName}/__tests__. Use the .test.ts infix.
Currently, testing utilities live partly at cli and partly at @n8n/backend-test-utils. In future, all testing utilities will be moved to common packages, to make modules more decoupled from cli.
LICENSE_FEATURES at packages/@n8n/constants/src/index.tsLOG_SCOPES at packages/@n8n/config/src/configs/logging.config.tsLicenseState at packages/@n8n/backend-common/src/license-state.tspackages/@n8n/db/src/migrationszod at @n8n/api-typespackages/@n8n/backend-common/src/modules/module-registry.tsLicense events (e.g. expiration) currently do not trigger module shutdown or initialization at runtime.
Some core functionality is yet to be moved from cli into common packages. This is not a blocker for module adoption, but this is desirable so that (a) modules become decoupled from cli in the long term, and (b) future external extensions can access some of that functionality.
Existing features that are not modules (e.g. LDAP) should be turned into modules over time.
insights module at packages/@n8n/modules/insights.packages/@n8n/{feature}. How does this work with modules? If your feature is already fully decoupled from cli, or if you know in advance that your feature will have zero dependencies on cli, then you already stand to gain most of the benefits of modularity. In this case, you can add a thin module to cli containing an entrypoint to your feature imported from your package, so that your feature is loaded only when needed.cli so you can use the usual watch command.cli so any imports from cli remain available, i.e. aim for decoupling but do not consider it a blocker for progress. Reach out if you think the module system needs expanding.