Plugin System

The Gentics Mesh plugin system allows you to write and deploy custom plugins which can enrich the existing REST API.

Typical example plugins are:

  • Comment plugin - A plugin to provide a commenting feature.

  • Like plugin - A plugin to store likes to specific nodes.

  • Sitemap plugin - A plugin which generates a sitemap XML file.

A plugin can access the filesystem or use the Gentics Mesh REST Client to interact with the Mesh server.


Check the Gentics Mesh Awesome List for plugins.

Plugin System


The plugin directory can be configured within the mesh.yml configuration file. Each plugin may place its own configuration file within its own plugin directory.

Plugin Lifecycle


Name Description


Plugin gets loaded and prepared for starting


Plugin gets started.


Plugin gets pre-registered. The plugin will stay in this mode util the server is ready to initialize them.


Plugin gets initialized. You can implement the MeshPlugin#initialize() method to initialize your plugin resources.


Plugin gets finally registered so that it can be used.


Name Description


Plugin registration gets removed. At this point the plugin integration with the server gets removed. REST and GraphQL extensions get removed.


Plugin gets shutdown. You can implement the MeshPlugin#shutdown() method to stop and free your plugin resources.


Plugin gets stopped.


Finally the plugin gets unloaded.


Plugin verticles can be deployed in various ways.

Automatically during start-up

Any plugin jar file which was found in the configured plugins folder will automatically be deployed during server startup.

Deployment via REST API

Plugins can be managed via the /api/v2/admin/plugins endpoint. It is possible to deploy, undeploy and read plugin information.

Plugin jar files which have been copied to the configured plugins folder can be deployed via the POST /api/v2/admin/plugins endpoint.

  "path" : "my-plugin.jar"

Any deployed plugin can be referenced by the id and loaded via the GET /api/v2/admin/plugins/:id.

  "id" : "hello-world",
  "name" : "Hello World 1",
  "manifest" : {
    "id" : "hello-world",
    "name" : "Hello World 1",
    "description" : "A dummy plugin",
    "version" : "1.0",
    "author" : "Joe Doe",
    "inception" : "2018-10-12T14:15:06.024Z",
    "license" : "Apache License 2.0"
Plugins will not be directly accessible when deployed since the deployment process will first pre-register them.

You can undeploy a plugin via the DELETE /api/v2/admin/plugins/:id endpoint.

Programmatically deployment

You can deploy plugins programmatically in your IDE of choice via the Java API. This is useful for integration testing or when creating custom Gentics Mesh server bundles.

Mesh mesh = Mesh.mesh();;

# Embedded in your IDE
mesh.deployPlugin(YourPlugin.class, "your-plugin").blockingAwait();


Gentics Mesh provides various events which can be acted upon. The events can be via the internal API or via the websocket endpoint.

Name Description


Emitted once a plugin is being deployed.


Emitted once a plugin has been pre-registered.


Emitted once a plugin has been registered.


Emitted once a plugin has been deployed.


Emitted when a plugin deployment fails.


Emitted once a plugin is being undeployed.


Emitted once a plugin has been undeployed.


Plugins will only be registered once the write quorum has been reached. Until then the deployed plugins will remain in the pre-registered status.

The registration of plugins in clustered mode utilizes a lock to prevent concurrent plugin initialization within the cluster.

Plugins will not be automatically undeployed or unregistered once the write quorum is no longer reached.
Plugins which use event handling should be aware that every plugin instance in the cluster will process the event. If this is not desireable a locking or negotiation mechansim should be used to prevent concurrent event handling.

Plugin Development


  • Can I access the Gentics Mesh Graph in order to add custom elements to it?

No this is not possible. Using the Graph API could potentially alter the Graph structure and cause data inconsistencies.

  • Using a REST client to interact with the Mesh Server seems inefficient. Is there maybe a direct way to interact with Gentics Mesh?

We are aware of this limitation and are working on a local client which would work without involving the HTTP stack.


  • UI In the future we will also support UI plugins. A plugin will be able to hook into the Gentics Mesh UI in order to add additional custom UI elements.