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 four predefined template libraries: Preact, µ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:4445/

This will scaffold a new project in the name directory and start a devServer on localhost:4445 and production widget 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
│   merkur.config.mjs
└── server
│   └── config
│       │   default.json
│       │   production.json
│       │   test.json
│   └── router
│       └── error
│       └── widgetAPI
│   │   app.js
│   │   server.js
│   └── static
│   │   // static files for serving from server
└── src
│   │   style.css
│   │   widget.js
│   └── views
│       │   View.jsx
│       │   ErrorView.jsx
│   └── entries
│       │   client.js
│       │   server.js
│   └── slots
│       │   HeadlineSlot.jsx
│   └── components
│       │   Counter.jsx
│       │   MerkurIcon.jsx
│       │   Welcome.jsx
│       │   WidgetDescription.jsx

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


The package.json contains predefined dependencies and defines some scripts, which use Merkur CLI:


The configuration file for Merkur CLI


This folder can contains the two entry points for your widget — src/entries/client.js and src/entries/server.js, which is default predefined in @merkur/{framework} module and you can create your own entries and override default one. In src/ folder you would store all code necessary for displaying the widget, such as React components, etc. Here is also the most important file widget.js file which is your main file for your widget.


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.


This contains a basic Express server with predefined middleware.