• English

      • Plugin

      In NocoBase, Server Plugin is the primary way to extend server-side functionality. You can extend the Plugin base class provided by @nocobase/server in your plugin directory's src/server/plugin.ts, then register events, APIs, permissions, and other custom logic at different lifecycle stages.

      Plugin Class

      A basic plugin class structure is as follows:

      import { Plugin } from '@nocobase/server';

export class PluginHelloServer extends Plugin {
  async afterAdd() {}

  async beforeLoad() {}

  async load() {}

  async install() {}

  async afterEnable() {}

  async afterDisable() {}

  async remove() {}

  async handleSyncMessage(message: Record<string, any>) {}

  static async staticImport() {}
}

export default PluginHelloServer;

      Lifecycle

      Plugin lifecycle methods execute in the following order. Each method has its specific execution timing and purpose:

      Lifecycle MethodExecution TimingDescription
      staticImport()Before plugin loadsStatic class method, executed during initialization phase independent of application or plugin state, used for initialization work that doesn't depend on plugin instances.
      afterAdd()Executed immediately after plugin is added to PluginManagerPlugin instance has been created, but not all plugins have finished initializing. Can perform some basic initialization.
      beforeLoad()Executed before all plugins' load()Can access all enabled plugin instances at this point. Suitable for registering database models, listening to database events, registering middleware, and other preparation work.
      load()Executed when plugin loadsAll plugins' beforeLoad() complete before load() starts. Suitable for registering resources, API interfaces, and other core business logic -- for example, registering custom REST APIs via resourceManager. Note: The database has not finished synchronizing during the load() phase, so you cannot perform database queries or writes -- database operations should be placed in install() or request handlers.
      install()Executed when plugin is first activatedOnly executed once when plugin is first enabled, typically used for initializing database table structures, inserting initial data, and other installation logic. install() only runs on first activation -- if subsequent versions need to change table structures or migrate data, use Migration scripts instead.
      afterEnable()Executed after plugin is enabledExecuted every time plugin is enabled, can be used to start scheduled tasks, establish connections, etc.
      afterDisable()Executed after plugin is disabledCan be used to clean up resources, stop tasks, close connections, etc.
      remove()Executed when plugin is removedUsed to write uninstallation logic, such as deleting database tables, cleaning files, etc.
      handleSyncMessage(message)Message synchronization in multi-node deploymentWhen the application runs in multi-node mode, used to handle messages synchronized from other nodes.

      Execution Order Description

      Typical execution flow of lifecycle methods:

      1. Static Initialization Phase: staticImport()
      2. Application Startup Phase: afterAdd() → beforeLoad() → load()
      3. First Plugin Enable Phase: afterAdd() → beforeLoad() → load() → install()
      4. Second Plugin Enable Phase: afterAdd() → beforeLoad() → load()
      5. Plugin Disable Phase: afterDisable() is executed when plugin is disabled
      6. Plugin Remove Phase: remove() is executed when plugin is removed

      In plugin development, you can access various APIs provided by the application instance through this.app -- this is the core entry point for extending plugin functionality. The app object contains various functional modules of the system, which you can use in plugin lifecycle methods.

      app Member List

      Member NameType/ModuleMain Purpose
      loggerLoggerRecord system logs, supporting info, warn, error, debug levels. See Logger
      dbDatabaseORM layer operations, model registration, event listening, transaction control, etc. See Database
      resourceManagerResourceManagerRegister and manage REST API resources and action handlers. See ResourceManager
      aclACLDefine permissions, roles, and resource access policies. See ACL
      cacheManagerCacheManagerManage system-level cache, supporting Redis, memory cache, and other backends. See Cache
      cronJobManagerCronJobManagerRegister and manage scheduled tasks, supporting Cron expressions. See CronJobManager
      i18nI18nMulti-language translation and localization. See I18n
      cliCLIRegister custom commands, extending NocoBase CLI. See Command
      dataSourceManagerDataSourceManagerManage multiple data source instances and their connections. See DataSourceManager
      pmPluginManagerDynamically load, enable, disable, and remove plugins, managing inter-plugin dependencies.
      Tip

      For detailed usage of each module, please refer to the corresponding documentation chapters.