Automated extension demo

How to automatically publish a demo of your Mozaïk extension (for free)

The best way to promote your brand new Mozaïk extension is to provide a demo for it.

But because we’re talking about open source stuff, you probably don’t want to spend money for a dedicated hosting, we’ll see how you can use a free heroku hosting to showcase your extension.

Also manual deployment is painful and hard to maintain, the goal is to automate everything so that you don’t have to worry about which version is deployed, your demo will always be up to date.



Create a dedicated branch

First, you’ll have to create a new orphan branch on your repository:

git checkout --orphan demo
git rm --cached -r .

Next, remove all unwanted files, make sure you don’t delete the .git directory.

Fetch the template

Now, you’ll have to get the Mozaïk extension demo template:

mv {mozaik-ext-demo-template-master/*,mozaik-ext-demo-template-master/.*} .
rm -r mozaik-ext-demo-template-master

Define proper settings

You need to adjust several files:

  • package.json: replace EXT_NAME, FULL_NAME, GITHUB_USER and set the correct version of your package
  • replace EXT_NAME
  • src/App.jsx: replace EXT_NAME

If your extension involves a client, tweak src/server.js by uncommenting the following lines and replacing EXT_NAME:

import EXT_NAME  from 'mozaik-ext-EXT_NAME/client'

mozaik.bus.registerApi('EXT_NAME', EXT_NAME)

Finally, edit dashboard configuration: config.js.

Test & push

npm install
npm start

Now open http://localhost:5000/ and check your dashboard works as expected.

If everything is OK, commit and push the demo branch:

git add . && git commit -m "feat(demo): init demo"
git push --set-upstream origin demo

Heroku setup

Login to your heroku account.

Create a new app

Click on the Create new app button located in the top right drop down.

new heroku app

Set your app name, should be something like mozaik-EXT_NAME and click on Create App to validate.

heroku app form

Connect your app to your GitHub repository, click on the GitHub button inside the Deployment method section.

heroku deployment method

Search for your repository and click the connect button.

heroku connect github

Enable auto deployment, choose the demo branch and click Enable Automatic Deploys inside the Automatic Deploys section. This will trigger a deploy each time you push to the demo branch.

heroku auto deployment

Add config vars, click on the Settings tab and click Reveal Config Vars, then add USE_SSL var with value true. This is required to tell Mozaïk to use https and wss.

heroku vars

It’s also a good opportunity to add required credentials if your extension relies on a http client requiring some (don’t put it in the repo!), those vars will then be available as regular environment variables.

Deploy your app by clicking on the Deploy tab, choosing the demo branch and clicking Deploy Branch inside the Manual Deploy section.

heroku deploy

Your app should be deployed in a few minutes and then availabe at To update the demo for newer releases, you’ll just have to edit the extension version in the package.json file from the demo branch, it will automatically re-deploy it.

Enjoy and share :)

You can now add the demo as your repository website on GitHub.

GitHub extension website

If you want to have a link to the demo on the Mozaïk website extensions page, feel free to fork the website repo and edit config.yaml or just create an issue, I’ll take care of it.