Fetching contributors…
Cannot retrieve contributors at this time
175 lines (116 sloc) 4.63 KB Builds

Gratipay Widgets + API

Getting Started with Development


$ git clone
$ cd
$ make run

Then visit http://localhost:9537/test/. For more details, read Development section below.


For now documentation for widgets API is present in JSDoc comments, but not generated into more readable format.

Configuration options:

  • window.grtpAPI - Where to look for the API
    • defaults to
  • window.gratipayURI - Where to look for Gratipay
    • defaults to


In the following examples, just switch out my-team with your Gratipay Team slug.

Standard Widgets

<script data-gratipay-teamslug="my-team"
  src="" async></script>

Custom Widgets

You can create your own widgets by adding data-gratipay-widget="custom" to your widget's HTML, and the following classes:

  • Text
    • gratipay-teamslug - the Team's slug
    • gratipay-receiving - dollar-sign prefixed value of receiving
  • Links
    • gratipay-profile-link - sets the href attribute to the Team's profile link
    • gratipay-link - sets the href attribute to
  • Misc styling
<div data-gratipay-teamslug="my-team" data-gratipay-widget="custom">
  I receive <a class="gratipay-profile-link">
    <span class="gratipay-receiving">$0.00</span> / wk
  on <a class="gratipay-link">Gratipay</a>.
<script src=""></script>

Shields can be created for ~users or projects:


<img src="">

( still uses "team" rather than "project.")


<img src="">

Other Widgets

Google Gadget for Blogger.

Development is a static site. But it is generated from sources.

Typical site like is divided into backend and frontend. backend is Python code that runs on server side. frontend is HTML+CSS+Javascript that is processed by browser. is pure frontend, but its HTML+CSS+Javascript sources from repository are not what is being run on the site. Before sources can be deployed, they need to be minified, tested and, if you write styles in SASS, the .sass files need to be compiled into CSS. So repository layout looks like:

lib/   - source files that need to be compiled
www/   - static files that are copied as-is

Javascript tools to build, lint and test source are similar to Python tools. This can be matched approximately as this:

JavaScript     |  Python
npm            |  pip
package.json   |, setup.cfg, requirements.txt
Grunt          |  make, fabric, SCons
Gruntfile.js   |  Makefile,, SConstruct

Grunt is popular JS build systems, and there are many others, like Gulp for example. It should be noted that npm itself has some kind of dependency management, so you may not need Grunt at all.

Release and Deployment is hosted on Heroku.


Bump version in package.json and create new tag.

Add the Heroku remote to your own local repo:

git remote add heroku

Then you can git push heroku master. The heroku/nodejs buildpack will then npm build the sources and save them in www/. heroku-buildpack-static takes over and serves web requests from the www directory.


In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.

To help keep a consistent style, we also recommend using EditorConfig.


Released into the public domain (per CC0).