Merkur - tool-storybook

Integrates Storybook with Merkur widgets. The package handles the widget lifecycle (create → mount → unmount) inside the Storybook loader pipeline, so your story files stay focused on rendering.

Full documentation and setup guide.

Installation

npm install --save-dev @merkur/tool-storybook

API

| Export | Description | |--------|-------------| | createPreviewConfig(options) | Registers a widget with Merkur and returns a partial Storybook preview.mjs config ({ loaders }). Spread into your preview export. | | createVanillaRenderer() | Creates a render/update pair for vanilla JS widgets that produce HTML strings. | | createWidgetLoader(options) | Low-level loader factory used internally by createPreviewConfig. Use directly when you need full control over widget registration. |

createPreviewConfig options

| Option | Type | Required | Description | |--------|------|----------|-------------| | widgetProperties | Object | ✅ | Widget definition object — must include name and version. | | render | Function | — | Called each time widget.update() fires, receives the widget instance. Defaults to a no-op. | | createWidget | Function | — | Widget factory. Defaults to createMerkurWidget from @merkur/core. |

createVanillaRenderer

createVanillaRenderer() takes no arguments.

• Stories must provide args.component as a function (widget) => htmlString.
• Event binding: define bindEventListeners(widget, container) (and optionally unbindEventListeners(widget, container)) directly on the widget inside its createWidget factory. The renderer calls widget.bindEventListeners(container) after each render and widget.unbindEventListeners(container) before each re-render. widget is auto-injected as the first argument by Merkur's bindWidgetToFunctions, so the signature in the definition must include widget as the first parameter.
• Security: args.component is responsible for HTML-escaping any dynamic values before returning the HTML string. Raw interpolation of user-controlled strings is injected via innerHTML as-is.

Peer dependencies

This package requires Storybook ≥ 10 (storybook/preview-api and storybook/internal/core-events are imported at runtime). Installing it alongside Storybook < 10 will cause a module-not-found error.

About Merkur

Merkur is a tiny extensible JavaScript library for front-end microservices. It supports server-side rendering out of the box and works with Preact, µhtml, Svelte, vanilla JS, and more.