How to Build a Heroku Add-On

Following the release of the Butter Heroku add-on, many folks expressed interest in what the process has been like. This post will hopefully provide a quick overview of how to take your idea from concept to publicly available in the Heroku ecosystem. We'll point you to the most important docs and give you a sense of the steps involved.

Getting Started

The best way to get going is to immerse yourself in these three documents:

• How Add-ons Work
• Building an Add-on
• Submitting an Add-on

How Add-ons Work

The TL;DR for this article is when someone "installs your add-on", there's a provisioning process that occurs. Basically Heroku will POST to an end point that you specify (via the add-on manifest) and that end point is responsible for 1) creating a new user account and 2) returning a unique string which get's stored as an ENV variable for the user's app.

The doc gives an example of MYSQL_URL=mysql://user:pass@mysqlhost.net/database  but in the case of Butter, we return your API key. This results in something like BUTTER_TOKEN=123456ABCEFG. So when you add Butter to your app, the Butter Rails engine automatically pulls your Butter API Key out of ENV['BUTTER_TOKEN'].

This results in a pretty slick user experience where your add-on's user never has to worry about configuring an API token.

Building an Add-on

This article is where you'll spend the most time. It takes you through every step of getting provisioning working. You'll want to install a tool they built called Kensa. It provides some basic commands that runs tests against the various end points you'll need to create.

Once you've gotten everything working and passing the kensa test's, you'll get to the exciting part. Submitting your add-on!

Submitting your Add-on

In order to submit your add-on for review, first create a provider account. Once created you'll upload your add-on manifest to the portal. As you learned in prior steps, the manifest tell Heroku where your provisioning end points live, which countries your add-on is available in, and so on.

The phases

Congrats! You're add-on has been accepted. Now the fun part, getting users, working the kinks out and progressing through the phases of an add-on.

Alpha

The first phase is alpha. Before your add-on can move into Beta you need to:

• Name your add-on
• Describe its key benefits
• Setup a feature list
• Upload an icon (70 by 70 pixels, PNG format)
• Provide an email address for support and feedback
• Create Dev Center documentation to be reviewed and approved
• Invite at least 10 alpha users, who accept and provision the add-on

These are all fairly straight forward. The most time consuming one is creating crisp documentation (unless of course you already have that). As you complete each, it will get checked off of the list in your provider dashboard.

Once you've checked everything off, shoot Heroku an email asking to promote your add-on to Beta.

Beta

Beta is where you stress test your add-on and get hundred of people using it. While in Beta, your add-on can only have one plan: Free. You can set up your plan pricing and tiers and fantasize about all the dough that's about to start rolling in; but until it's in GA status you won't be able to charge anything.

Most importantly, Beta is when everyone will see your add-on actually appear in the add-on market place. Note that it is clearly marked as "Beta". This is when you can expect to see the benefit of being the marketplace take effect as folks add your add-on to their apps.

GA

Getting approved into GA is a little less objective. There's not a specific checklist to complete per-se other than getting as many people using your add-on as possible. Heroku uses the term "hundreds". Once in GA you can start charging for your add-on.

Our experience

Butter is currently in the Beta phase and our experience so far has been great. Heroku's docs do a nice job of outlining the process and setting expectations. We're looking forward to moving into the final GA phase.

Hopefully this guide has been helpful. If you decide to build an add-on, let us know! And if your add-on needs an awesome blog, do give Butter a try.

If you have any questions, leave a comment below.

*Update* - Butter has been promoted into GA and we're excited to be the leading CMS add-on in Heroku's Content Management category!