Getting started

Installation

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:

<name>
│   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
│   │
│   └───component
│       │   Counter.jsx
│       │   MerkurIcon.jsx
│       │   View.jsx
│       │   Welcome.jsx
│       │   WidgetDescription.jsx

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

package.json

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

src

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.

server

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

server/config

Merkur use config module for hierarchical configurations for your widget.

server/router

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.

app.js

This contains a basic Express server with predefined middleware.