Skip to main content

Getting started

Installation​

We recommend creating a new Merkur 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 JavaScript (or you can easily add your own).

npx @merkur/create-widget <n>

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:

<name>
│   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.

package.json​

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

  • npm run dev - start the widget in development mode, and watch source files for changes
  • npm run build - build the widget in production mode
  • npm test - run the tests
  • npm start - start the app in production mode after you've built it

merkur.config.mjs​

The configuration file for Merkur CLI

src​

This folder contains the two entry points for your widget — src/entries/client.js and src/entries/server.js, which are predefined in the @merkur modules based on your chosen view library. You can create your own entries and override the default ones. In the src/ folder you would store all code necessary for displaying the widget, such as components. Here is also the most important file widget.js which is your main file for your widget.

server​

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

server/config​

Merkur uses 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.

app.js​

This contains a basic Express server with predefined middleware.