Display Your Sponsors in Your GitHub READMEs
A nice way to reward your sponsors is to show them in your GitHub projects, and your READMEs are the obvious place. This article shows you how.
There are several ways to display your sponsors in your GitHub READMEs. This article uses SponsorKit created by Anthony Fu.
antfu/sponsorkit💖 Toolkit for generating sponsors images 😄
SponsorKit is a toolkit for generating sponsors images that supports GitHub Sponsors, Open Collective, Patreon, and Afdian.
Here’s how Anthony uses it himself in antfu/unplugin-auto-import README.
Let’s build our own sponsors image with our GitHub sponsors!
Prerequisites#
Before you start, you’ll need a GitHub account and at least one sponsor.
You’ll also need a new GitHub personal access token (classic) with the read:org and read:user scopes. Name it whatever you want, and keep its value somewhere for the next steps.
You can find more information about how to create a GitHub token in the GitHub documentation.
Create Your Repository#
To help you, we’ve created a template repository you can use to create your own: https://github.com/Open-reSource/sponsorkit-starter.
Open-reSource/sponsorkit-starterStarter template for SponsorKit
From the Starter Template#
You can click on the “Use this template” button to create your own repository.
Then fill in the form with the name of your repository, a description, and choose if you want to make it public or private. Click on the “Create repository from template” button to create your repository.
It will launch a GitHub Action that will fail, but don’t worry, we’ll fix that in the next steps.
From a New Repository#
You can also create your repository from scratch, clone it locally, and then run the following command:
npx degit Open-reSource/sponsorkit-starterConfigure Your Repository#
Your new repository is now created, and should contain the following files:
.github/workflows/scheduler.ymlthat runs the SponsorKit action on a schedule every day, for each merge on the main branch, or manually..env.exampleas described in SponsorKit usage.build.shscript to generate the sponsors images.package.jsonrelying on the latest version of SponsorKit and containing the build script.sponsor.config.tsthat contains the configuration for the generation of the sponsors images.
Change Default Permissions of GITHUB_TOKEN#
First, change the default permissions of the GITHUB_TOKEN that is used by the GitHub Action to commit and push the generated sponsors images.
Go to your repository settings, then to the “Actions” section, and choose “Read and write permissions” for the “Workflow permissions” option.
You can find more information about this configuration in the GitHub documentation.
Set up the environment variable#
By looking at .github/workflows/scheduler.yml, we can see that it relies on a ${{ secrets.SPONSORS_TOKEN }} environment variable.
We’ll need to set it up in the GitHub repository settings with “SPONSORS_TOKEN” as a name, and with the value of the GitHub personal access token that we created in the prerequisites.
You can find more information about how to create a new repository secret in the GitHub documentation.
Configure the GitHub Action#
Either after having cloned your repository locally, or directly on GitHub, you’ll need to edit the .github/workflows/scheduler.yml to indicate your GitHub username as a value for “SPONSORKIT_GITHUB_LOGIN”.
Commit and push your changes.
Check Your Generated Images#
This latter change will trigger the GitHub Action that will generate your sponsors images, commit, and push them at the root level of your repository with the message ” chore: update sponsors.svg”.
For example, you can see the generated sponsors images of the julien-deramond/static repository created from this same template.
(Optional) Generate The Images Locally#
More information
You can also run it locally, though you rarely need to.
You’ll need to install the dependencies by running npm i in your terminal.
Then, copy .env.example to .env still at the root level of your repository with the following content:
; GitHub provider.
; Token requires the `read:user` and `read:org` scopes.
SPONSORKIT_GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
SPONSORKIT_GITHUB_LOGIN=usernameSPONSORKIT_GITHUB_TOKENis the GitHub token you created earlier.SPONSORKIT_GITHUB_LOGINis your GitHub username.
The final step is to run npm run build in your terminal to generate the static files:
ju ߷ ~/j/static ➤ (main) npm run build (0.060674 hrs)
17:48:16
SponsorKit v0.8.3
✔ Loaded from cache ./.cache.json 17:48:16
✔ Wrote to ./sponsors.json 17:48:16
ℹ Composing SVG... 17:48:16
✔ Wrote to ./sponsors.svg 17:48:16
✔ Wrote to ./sponsors.png 17:48:16
17:48:17
SponsorKit v0.8.3
✔ Loaded from cache ./.cache.json 17:48:17
✔ Wrote to ./sponsors.wide.json 17:48:17
ℹ Composing SVG... 17:48:17
✔ Wrote to ./sponsors.wide.svg 17:48:17
✔ Wrote to ./sponsors.wide.png 17:48:17
17:48:17
SponsorKit v0.8.3
✔ Loaded from cache ./.cache.json 17:48:17
✔ Wrote to ./sponsors.part1.json 17:48:17
ℹ Composing SVG... 17:48:17
✔ Wrote to ./sponsors.part1.svg 17:48:17
✔ Wrote to ./sponsors.part1.png 17:48:18
17:48:18
SponsorKit v0.8.3
✔ Loaded from cache ./.cache.json 17:48:18
✔ Wrote to ./sponsors.part2.json 17:48:18
ℹ Composing SVG... 17:48:18
✔ Wrote to ./sponsors.part2.svg 17:48:18
✔ Wrote to ./sponsors.part2.pngAll the images are now generated at the root level of your repository. You can check them out in your file explorer.
Warning: Once it’s done, please don’t forget to remove at some point your GitHub token from the .env file for security reasons. You probably won’t re-run it from your local machine.
Use the Generated Images in Your READMEs#
Now that the GitHub Action has run, you can use the generated images in your READMEs.
For example, you can use the sponsors.svg image in your README.md file by adding the following code. Don’t forget to replace username by your GitHub username in the link’s href, link’s aria-label, and image’s src attributes.
<p align="center">
<a href="https://github.com/sponsors/username/" aria-label="Go to username's sponsors page">
<img src="https://cdn.jsdelivr.net/gh/username/static/sponsors.svg" />
</a>
</p>Warning: GitHub can take a while to render the image in your README. If you don’t see it, wait and refresh the page. On my side, it took around 10 minutes to be displayed. As long as the https://cdn.jsdelivr.net/gh/username/static/sponsors.svg URL is showing the image, don’t worry, it will be displayed in your README soon.
Final Result#
You can check my own personal sponsors list generated by following this article:
And find it integrated in one of my projects: https://github.com/julien-deramond/update-issue-body#sponsors.