Migrating legacy plugins to the Kibana Platform

The general architecture of legacy server-side code is similar to the Kibana Platform architecture in one important way: most legacy server-side plugins define an init function where the bulk of their business logic begins, and they access both core and plugin-provided functionality through the arguments given to init. Rarely does legacy server-side code share stateful services via import statements.

Although not exactly the same, legacy plugin init functions behave similarly today as Kibana Platform setup functions. KbnServer also exposes an afterPluginsInit method, which behaves similarly to start. There is no corresponding legacy concept of stop.

Despite their similarities, server-side plugins pose a formidable challenge: legacy core and plugin functionality is retrieved from either the hapi.js server or request god objects. Worse, these objects are often passed deeply throughout entire plugins, which directly couples business logic with hapi. And the worst of it all is, these objects are mutable at any time.

The key challenge to overcome with legacy server-side plugins will decoupling from hapi.

The legacy plugin system in the browser is fundamentally incompatible with the Kibana Platform. There is no client-side plugin definition. There are no services that get passed to plugins at runtime. There really isn’t even a concrete notion of core.

When a legacy browser plugin needs to access functionality from another plugin, say to register a UI section to render within another plugin, it imports a stateful (global singleton) JavaScript module and performs some sort of state mutation. Sometimes this module exists inside the plugin itself, and it gets imported via the plugin/ webpack alias. Sometimes this module exists outside the context of plugins entirely and gets imported via the ui/ webpack alias. Neither of these concepts exists in the Kibana Platform.

Legacy browser plugins rely on the feature known as uiExports/, which integrates directly with our build system to ensure that plugin code is bundled together in such a way to enable that global singleton module state. There is no corresponding feature in the Kibana Platform, and in the fact we intend down the line to build Kibana Platform plugins as immutable bundles that can not share state in this way.

The key challenge to overcome with legacy browser-side plugins will be converting all imports from plugin/, ui/, uiExports, and relative imports from other plugins into a set of services that originate at runtime during plugin initialization and get passed around throughout the business logic of the plugin as function arguments.

To move a legacy plugin to the new plugin system, the challenges on the server and in the browser must be addressed.

The approach and level of effort varies significantly between server and browser plugins, but at a high level, the approach is the same.

First, decouple your plugin’s business logic from the dependencies that are not exposed through the Kibana Platform, hapi.js, and Angular.js. Then introduce plugin definitions that more accurately reflect how plugins are defined in the Kibana Platform. Finally, replace the functionality you consume from the core and other plugins with their Kibana Platform equivalents.

Once those things are finished for any given plugin, it can officially be switched to the new plugin system.

No. That said, the migration process will require a lot of refactoring, and TypeScript will make this dramatically easier and less risky.

Although it’s not strictly necessary, we encourage any plugin that exposes an extension point to do so with first-class type support so downstream plugins that are using TypeScript can depend on those types.

Some core services are purely presentational, for example core.overlays.openModal(), where UI code does need access to these deeply within your application. However, passing these services down as props throughout your application leads to lots of boilerplate. To avoid this, you have three options:

If you find that you need many different core services throughout your application, this might indicate a problem in your code and could lead to pain down the road. For instance, if you need access to an HTTP Client or SavedObjectsClient in many places in your React tree, it’s likely that a data layer abstraction (like Redux) could make developing your plugin much simpler.

Without such an abstraction, you will need to mock out core services throughout your test suite and will couple your UI code very tightly to core. However, if you can contain all of your integration points with core to Redux middleware and reducers, you only need to mock core services once and benefit from being able to change those integrations with core in one place rather than many. This will become incredibly handy when core APIs have breaking changes.

There is no formal notion of common code that can safely be imported from either client-side or server-side code. However, if a plugin author wishes to maintain a set of code in their plugin in a single place and then expose it to both server-side and client-side code, they can do so by exporting the index files for both the server and public directories.

Plugins should not ever import code from deeply inside another plugin (e.g. my_plugin/public/components) or from other top-level directories (e.g. my_plugin/common/constants) as these are not checked for breaking changes and are considered unstable and subject to change at any time. You can have other top-level directories like my_plugin/common, but our tooling will not treat these as a stable API, and linter rules will prevent importing from these directories from outside the plugin.

The benefit of this approach is that the details of where code lives and whether it is accessible in multiple runtimes is an implementation detail of the plugin itself. A plugin consumer that is writing client-side code only ever needs to concern themselves with the client-side contracts being exposed, and the same can be said for server-side contracts on the server.

A plugin author, who decides some set of code should diverge from having a single common definition, can now safely change the implementation details without impacting downstream consumers.

Most of the utilities you used to build legacy plugins are available in the Kibana Platform or Kibana Platform plugins. To help you find the new home for new services, use the tables below to find where the Kibana Platform equivalent lives.