Easy demo site set up for your Ember.js addon

17 November 2017

I recently started a new Ember addon, ember-cancelable-button, and asked
for feedback on Twitter. I was promptly reminded (and rightly so) that for
any component-based add-on, there needs to be a demo site that shows examples
and where people can play with it. I thought setting this up would be a lot
harder than it turned out to be, and in this post I want to show you the
required steps.

Use the dummy app

When you generate a new addon with ember addon, you get a “dummy” app under
tests/dummy which is used to show your addon in action. That way, most of the
challenge of how to create an application to show off your work is already
solved by Ember CLI itself (one more reason to love frameworks and tools).

Use ember-code-snippet for … snippets

Since an add-on is for other developers to use, chances are you want to show
relevant code snippets (preferably code-highlighted) for how to use your add-on,
not just what users would see from it.

I was looking for a way to do this right next to the relevant UI case, and found
the excellent ember-code-snippet add-on.

Including the code snippet happens via a call to code-snippet, where name
should be the filename of your snippet (the language is inferred from the file
extension). However, there is one small change you need to make in order for
your snippet files to be looked up in the dummy app.

The default snippet folder is snippets but your probably want to place the
snippets in the dummy app. You can configure this in ember-cli-build.js:

And then push the built site to Github (just as the exit blurb suggests):

1

$ git push origin gh-pages:gh-pages

(If you don’t see your changes right away, don’t despair: it might take a few
minutes for caches to be invalidated.)

Automating release and deployment

Funnily enough, when I recently fixed a bug and released a new version of
ember-cancelable-button, I forgot to also rebuild and deploy the demo site
to Github pages. So it seemed like the bug wasn’t fixed and I promptly got an
error report about it.

In the thread of the issue, Jan Buschtöns gave me the idea to automate the
process of deploying the demo site when a new version of the add-on is released.

Unsurprisingly for us in the Ember community, I’ve found that there is an add-on
for this, called ember-cli-release.

So we start out by installing the add-on:

1

$ ember install ember-cli-release

, which creates a config/release.js file in our add-on folder.

The add-on has a great, detailed README, so let me just show you the
changes I made to the generated configuration to suit the auto-deploy scenario
(I snatched the below configuration from ember-light-table):