Merkur Top-Level API


Merkur is a tiny extensible library and has got a few base methods by default.

Module has some other utils methods which are useful for plugins.


The method accepts an object with property $plugins which can extend Merkur interface. Please note that the plugin setup method may be called more than once - you will have to make an extra check so you won’t redefine the plugin accidentally.

import { createMerkur } from '@merkur/core';

const myDummyMerkurPlugin = {
  setup(merkur) {
    if (typeof merkur.dummy === 'function') {

    merkur.dummy = () => {
      console.log('My dummy function');

const merkur = createMerkur({
  $plugins: [myDummyMerkurPlugin]

Merkur instance

The Merkur instance contains three predefined properties $in, $external and $dependencies. The property $in is for internal usage of merkur plugins or Merkur itself. Other properties are for your own usage. The properties $external and $dependencies are for storing values and sharing dependencies.

import { getMerkur } from '@merkur/core';

// {
//   $in: {
//     widgetFactory: {},
//   },
//   $external: {},
//   $dependencies: {},
//   register,
//   create,
// };

Other important part of the Merkur instance are methods register and create. The register method register widget to Merkur with a name, version and createWidget properties. The create method returns a new instance of the registered widget with defined properties.

import { getMerkur } from '@merkur/core';

const merkur = getMerkur();
const widgetProperties = {
  name: 'my-wdiget',
  version: '0.0.1',
  createWidget: () => {
    // your defined factory function

const widget = merkur.create(widgetProperties);