@harlan-zw/nuxt-github-sponsors

Nuxt GitHub Sponsors

Show your GitHub sponsors on your Nuxt site from typed data.

Why Nuxt GitHub Sponsors?

A sponsor page looks simple until you call the GitHub API. You may see:

• 📄 Pagination by hand: GitHub GraphQL returns sponsorships in pages, so you write the loop yourself.
• 🔒 Private sponsors in the response: Raw GitHub data includes sponsors who asked to stay private.
• 🕳️ Empty sponsor lists in production: A missing token or a failed fetch bakes an empty list into the deploy.

Nuxt GitHub Sponsors fetches your GitHub sponsors and gives them to your app as typed data. It ships no UI, so you design your own sponsor page.

Features

• 🔌 Route and composable: You list every active sponsor without writing GitHub GraphQL pagination yourself.
• 🔒 Private sponsors filtered: Private sponsors and raw GitHub data never leave your server.
• 🏅 Tiers and overrides: You group sponsors by monthly amount and fix a wrong name, avatar, or link without touching GitHub.
• 🔤 Tier keys typed from config: A renamed tier fails to compile, so no page shows an empty tier by mistake.
• ⚡ One-day SWR cache: Page views stop calling the GitHub API on each visit, and a failed fetch never sticks in the cache.
• 🎨 Headless by design: You build the sponsor page in your own design, with no bundled component to fight.

Installation

npx nuxi@latest module add @harlan-zw/nuxt-github-sponsors

[!TIP] Generate an Agent Skill for this package using skilld:

npx skilld add @harlan-zw/nuxt-github-sponsors

export default defineNuxtConfig({
  modules: ['@harlan-zw/nuxt-github-sponsors'],
  githubSponsors: {
    login: 'your-github-login',
  },
})

Set NUXT_GITHUB_SPONSORS_TOKEN. The token must be a classic token, because a fine-grained token cannot call the GitHub GraphQL API.

Options

Set tokenEnv when the default name is already taken:

export default defineNuxtConfig({
  githubSponsors: {
    login: 'your-github-login',
    tokenEnv: 'NUXT_GITHUB_AUTH_TOKEN',
  },
})

Modes

prerender bakes the route at build. It needs the token at build time. If the token is absent, the module warns and skips the prerender, so no empty sponsor list is baked into the deploy.

runtime serves the route from the server with a one-day SWR cache.

client skips server rendering. The page fetches after mount, so sponsors stay out of the rendered HTML and need no onMounted gate of your own.

Tier keys

The module types the tier keys from your configured tiers. TypeScript checks tiers.top against your config. If you rename a tier, the page fails to compile and does not render an empty list.

Usage

The module registers a public route and useGitHubSponsors(). The server fetches every page of active sponsorships and drops private sponsors. It sends a minimal public DTO, then applies your overrides and tiers.

This package has no sponsor UI. Call useGitHubSponsors() for a typed response, and build the page yourself.

Failure states

The route always answers 200 with a tagged state. unavailable with reason not-configured means no token. unavailable with reason upstream-error carries an errorTag naming the upstream fault. Both states carry an empty collection, so a page renders and a prerender with failOnError still builds. The cache stores only successful upstream results. The module logs no secret.

If an override key matches no sponsor, the server logs a warning. Without it, a key with a typo would do nothing.

Sponsors

License

Licensed under the MIT license.