Getting started


We recommend creating a new Mekur widget using @merkur/create-widget, which sets up everything automatically for you. You can use one of six predefined template libraries: React, Preact, hyperHTML, µhtml, Svelte or vanilla (or you can easily add your own).

npx @merkur/create-widget <name>

cd name

npm run dev // Point your browser at http://localhost:4444/

This will scaffold a new project in the name directory and start a server on localhost:4444. Try editing a few files to get a feel for how everything works.

Merkur - hello widget

Widget structure

If you take a look inside the created widget, you’ll see this file structure:

│   package.json
│   webpack.config.js
└── server
│   └── config
│       │   default.json
│       │   production.json
│       │   test.json
│   └── router
│       └── error
│       └── playground
│       └── widgetAPI
│   │   app.js
│   │   server.js
│   └── static
│   │   // static files for serving from server
└── src
│   │   style.css
│   │   widget.js
│   │   client.js
│   │   server.js
│   └── lib
│       │   utils.js
│   └── views
│       │   View.jsx
│       │   ErrorView.jsx
│   └── slots
│       │   HeadlineSlot.jsx
│   └── components
│       │   Counter.jsx
│       │   MerkurIcon.jsx
│       │   Welcome.jsx
│       │   WidgetDescription.jsx

You’ll notice a few extra files for ESLint, Babel and Jest config.


The package.json contains predefined dependencies and defines some scripts:


This folder contains the two entry points for your widget — src/client.js and src/server.js. Here you would store all code necessary for displaying the widget, such as React components.


The server folder contains assets, predefined config per environment, routes and most importantly the app.js file.


Merkur uses config module for hierarchical configurations for your widget.


This contains individual Express routes. The most important route is widgetAPI which defined widget API interface. You can find here also playground route for development purpose.


This contains a basic Express server with predefined middleware.