SponsorKit으로 오픈소스 후원자에게 감사하기

오픈소스 프로젝트에 후원해주시는 분들이 계신다면 README에서 제대로 소개해드리고 싶을 텐데요. GitHub Sponsors나 Open Collective 같은 플랫폼에서 후원자 목록을 가져와 직접 이미지를 만들려면 꽤 손이 많이 갑니다. 이런 작업을 한 방에 해결해주는 도구가 바로 SponsorKit이에요.

이전에 All Contributors로 오픈소스 기여자를 인정하는 방법을 알아봤는데요, 이번에는 후원자를 시각적으로 멋지게 표현하는 방법을 살펴보겠습니다.

SponsorKit이란?

SponsorKit은 여러 후원 플랫폼에서 후원자 정보를 가져와 SVG나 PNG 같은 이미지로 자동 생성해주는 도구입니다. Vitest, UnoCSS, Slidev 등 수많은 오픈소스 프로젝트로 유명한 Anthony Fu가 만들었어요.

지원하는 후원 플랫폼은 꽤 다양합니다.

플랫폼설명
GitHub SponsorsGitHub 내장 후원 시스템
Open Collective오픈소스 재정 관리 플랫폼
Patreon창작자 후원 플랫폼
Polar오픈소스 개발자 후원 플랫폼
Afdian (爱发电)중국 창작자 후원 플랫폼
Liberapay정기 기부 플랫폼

여러 플랫폼의 후원자를 한곳에 모아서 하나의 이미지로 만들 수 있다는 게 큰 장점이죠.

빠르게 시작하기

가장 간단한 방법은 npx로 바로 실행하는 거예요.

$ npx sponsorkit

이 명령어를 실행하면 ./sponsorkit/ 디렉토리에 후원자 이미지가 만들어집니다. 물론 실행 전에 후원 플랫폼의 API 토큰을 환경 변수로 설정해둬야 해요.

GitHub Sponsors를 사용한다면 .env 파일에 토큰을 아래처럼 넣어주면 됩니다.

.env
SPONSORKIT_GITHUB_TOKEN=ghp_xxxxxxxxxxxx
SPONSORKIT_GITHUB_LOGIN=your-username

GitHub 토큰은 read:userread:org 스코프가 필요합니다. GitHub 설정 페이지에서 발급받을 수 있습니다.

실행이 끝나면 다음 파일이 생깁니다.

  • sponsors.json — 후원자 원본 데이터
  • sponsors.svg — 벡터 이미지
  • sponsors.png — 래스터 이미지

설정 파일 작성

프로젝트 루트에 sponsorkit.config.js 파일을 만들어서 세부 설정을 잡아보겠습니다.

sponsorkit.config.js
import { defineConfig, tierPresets } from "sponsorkit";

export default defineConfig({
  github: {
    login: "your-username",
    type: "user",
  },

  width: 800,
  outputDir: "./sponsorkit",
  formats: ["json", "svg", "png"],

  tiers: [
    {
      title: "Past Sponsors",
      monthlyDollars: -1,
    },
    {
      title: "Backers",
      preset: tierPresets.base,
    },
    {
      title: "Sponsors",
      monthlyDollars: 10,
      preset: tierPresets.medium,
    },
    {
      title: "Silver Sponsors",
      monthlyDollars: 50,
      preset: tierPresets.large,
    },
    {
      title: "Gold Sponsors",
      monthlyDollars: 100,
      preset: tierPresets.xl,
    },
  ],
});

tiers 배열로 후원 금액에 따라 계층을 나눌 수 있어요. monthlyDollars는 그 계층의 최소 월 후원 금액이고 -1은 과거 후원자(현재 후원 중지)를 뜻합니다.

티어 프리셋

아바타 크기나 이름 표시 여부를 정하는 프리셋이 미리 준비되어 있어요.

프리셋아바타 크기이름 표시용도
xs25px소액 후원자
small35px일반 후원자
base40px기본 후원자
medium50px중간 후원자
large70px큰 후원자
xl90px최상위 후원자

medium 이상부터는 아바타 아래에 후원자 이름도 함께 표시돼요. 후원 금액이 클수록 아바타도 커지니까 후원자 입장에서 보람을 느낄 수 있겠죠.

렌더러 선택

이미지를 그리는 렌더러는 두 가지가 있어요.

먼저 기본값인 Tiers 렌더러가 있습니다. 후원자를 금액별 계층으로 나눠서 가로 행으로 배치하는 방식인데요. 각 계층마다 제목이 표시되고 후원 금액이 높을수록 아바타가 크게 나옵니다.

sponsorkit.config.js
export default defineConfig({
  renderer: "tiers",
});

다른 하나는 Circles 렌더러예요. d3-hierarchy의 원형 패킹(circle packing) 알고리즘을 써서 후원 금액에 비례하는 원형으로 후원자를 배치합니다. 시각적으로 독특한 느낌을 줄 수 있죠.

sponsorkit.config.js
export default defineConfig({
  renderer: "circles",
  circles: {
    radiusMax: 300,
    radiusMin: 10,
    radiusPast: 5,
  },
});

여러 이미지 한 번에 생성

설정 하나로 여러 스타일의 이미지를 한꺼번에 뽑아낼 수도 있는데요. 예를 들어 README용 넓은 이미지와 웹사이트용 원형 이미지를 동시에 만들 수 있죠.

sponsorkit.config.js
export default defineConfig({
  renders: [
    {
      name: "sponsors.wide",
      width: 1200,
      renderer: "tiers",
    },
    {
      name: "sponsors.circles",
      width: 600,
      renderer: "circles",
    },
  ],
});

여러 플랫폼 통합

GitHub Sponsors 외에 다른 플랫폼도 함께 사용한다면 각 플랫폼의 토큰을 .env 파일에 추가하면 돼요.

.env
# GitHub Sponsors
SPONSORKIT_GITHUB_TOKEN=ghp_xxxxxxxxxxxx
SPONSORKIT_GITHUB_LOGIN=your-username

# Open Collective
SPONSORKIT_OPENCOLLECTIVE_KEY=xxxxxxxxxxxx
SPONSORKIT_OPENCOLLECTIVE_SLUG=your-collective

# Patreon
SPONSORKIT_PATREON_TOKEN=xxxxxxxxxxxx

# Polar
SPONSORKIT_POLAR_TOKEN=xxxxxxxxxxxx
SPONSORKIT_POLAR_ORGANIZATION=your-org

SponsorKit이 알아서 여러 플랫폼의 후원자를 합쳐서 하나의 이미지로 만들어줍니다. 같은 사람이 여러 플랫폼에서 후원하고 있으면 sponsorsAutoMerge 옵션으로 자동 병합도 가능해요.

sponsorkit.config.js
export default defineConfig({
  sponsorsAutoMerge: true,
});

GitHub Actions로 자동화

수동으로 이미지를 만드는 것도 좋지만 GitHub Actions를 쓰면 매일 자동으로 후원자 이미지를 업데이트할 수 있습니다.

.github/workflows/sponsors.yml
name: Update Sponsors

on:
  schedule:
    - cron: "0 0 * * *" # 매일 자정
  workflow_dispatch: # 수동 실행

jobs:
  sponsors:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npx sponsorkit

        env:
          SPONSORKIT_GITHUB_TOKEN: ${{ secrets.SPONSORKIT_GITHUB_TOKEN }}
          SPONSORKIT_GITHUB_LOGIN: your-username

      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: update sponsor images"

이 워크플로우는 매일 자정에 실행되면서 후원자 이미지를 최신 상태로 유지해줍니다. 생성된 이미지를 README에 넣어두면 새 후원자가 추가될 때마다 자동으로 반영되죠.

프로그래밍 방식으로 사용

CLI뿐 아니라 Node.js 코드에서 직접 후원자 데이터를 끌어올 수도 있어요. 후원자 데이터를 가공해서 웹사이트에 표시하거나 커스텀 이미지를 만드는 등 원하는 대로 활용할 수 있습니다.

generate.mjs
import { fetchSponsors } from "sponsorkit";

const sponsors = await fetchSponsors({
  github: {
    token: process.env.GITHUB_TOKEN,
    login: "your-username",
  },
});

console.log(`총 ${sponsors.length}명의 후원자`);

for (const sponsor of sponsors) {
  console.log(`${sponsor.sponsor.name}: $${sponsor.monthlyDollars}/월`);
}

각 후원자 객체에는 이름과 아바타 URL, 월 후원 금액, 후원 플랫폼 등이 담겨 있어서 여러 곳에서 활용하기 좋죠.

마치며

지금까지 SponsorKit을 사용해서 오픈소스 후원자 이미지를 자동으로 만드는 방법을 알아봤습니다.

이전에 다뤘던 All Contributors는 코드나 문서 등 여러 기여를 인정하는 쪽이었죠. SponsorKit은 거기서 한발 더 나아가 재정적으로 프로젝트를 지원하는 후원자를 눈에 보이게 표현해줍니다. 두 도구를 함께 쓰면 오픈소스 프로젝트에 기여하는 모든 분을 빠짐없이 인정할 수 있겠죠. 💪

후원을 받고 계신 오픈소스 메인테이너라면 SponsorKit 한번 써보세요. 후원자분도 분명 좋아하실 거예요. 😊

더 많은 설정 예시가 궁금하다면 SponsorKit 공식 저장소를 참고해보세요!

This work is licensed under CC BY 4.0 CC BY

Discord