Gratipay Widgets + API
JavaScript HTML Nginx Other
Latest commit 9c900f4 Feb 10, 2017 @whit537 whit537 committed on GitHub Merge pull request #164 from gratipay/challenge-dir
Make ACME challenge dir accessible
Failed to load latest commit information.
bin remove www from urls Aug 29, 2014
infra Make ACME challenge dir accessible Feb 10, 2017
test Update nomenclature in tests Jun 30, 2016
www index.html: Link to examples is more useful Feb 2, 2015
Makefile Rename command 'deploy' -> 'build' Mar 9, 2015
package.json Builds

Gratipay widgets + widget 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 a Digital Ocean VPS (called droplet) accessible through SSH. It runs nginx and the publishing root is /home/

To access the server, you need someone who already has access to add your key to /home/

Look in the infra/ directory in this repo for deployment files. In production, infra/nginx.conf in symlinked to /etc/nginx/sites-enabled/, and infra/post-receive to /home/

Initial Server Setup

The system-application layout is following:

/etc/nginx/sites-enabled/  - nginx config
/home/          - code checkout
                                  - auto-update script

Then use root/sudo to create user grtp with home at and install required packages - nginx, git.

adduser grtp --home=/home/ --disabled-password --gecos ""
apt-get install nginx git

# now log into grtp user
su grtp

With new grtp user:

cd ~
git clone production
cd production

Setup automatic update on push:

cp infra/post-receive .git/hooks/
chmod +x .git/hooks/post-receive


Bump version in package.json and create new tag.

Add the remote to your own local repo:

git remote add prod

Then you can git push prod. The post-receive hook will update the filesystem on the droplet and runs the grunt build task that minifies code and copies files from lib to www, and then it will reload nginx configuration.


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).