AristoBadges

AristoBadges is a minimal, cache-friendly SVG badge service for GitHub repos, orgs, and NPM packages. Built for README dashboards with fast server-side rendering and predictable URLs.

Pick a template URL, add your values, and drop the SVG into any README.

---

---

---

🔀 Repository Badge

Activity, releases, and engagement for a single repo.

👤 Organisation Badge

Org-wide stars, repos, forks, PRs, issues and activity.

📦 NPM Package Badge

Version and downloads for an NPM package.

---

🔗 Links

• Documentation: https://ui.aristobyte.com
• GitHub Org: https://github.com/aristobyte-ui
• Repository: https://github.com/aristobyte/aristo-badges
• Releases: https://github.com/aristobyte/aristo-badges/releases
• NPM Org: https://www.npmjs.com/org/aristobyte-ui

---

⚡ Endpoints

Repository Badge

https://badges.aristobyte.com/api/repo?owner=<ORG_OR_USER>&repo=<REPO>

Organisation or Owner Badge

https://badges.aristobyte.com/api/org?org=<ORG>

NPM Package Badge

https://badges.aristobyte.com/api/npm?namespace=<SCOPE>&pkg=<PACKAGE>

---

🧭 Project Architecture

• App type: Next.js App Router (app/)
• Locale entry flow:
  • app/page.tsx redirects to fallback locale (en-gb)
  • app/[locale]/page.tsx renders the main UI
• Public API routes:
  • app/api/repo/route.ts
  • app/api/org/route.ts
  • app/api/npm/route.ts
• Shared API internals: app/api/_lib/ (request parsing, data sources, formatters, SVG mappers/templates, response helpers)
• Main UI composition: SiteHeader, ProjectInfo, QuickLinks, BadgesBuilder, FooterNote (components/)
• Config + i18n:
  • config/index.ts
  • hooks/useConfig.tsx
  • hooks/useTranslation.tsx
  • translations/ (fallback locale: en-gb)
• URL builders for previews/copy actions: utils/url.ts
• Testing:
  • Unit tests: *.unit.test.ts(x)
  • Server tests: *.server.test.ts(x)
  • API tests: app/api/_lib/__tests__/
• Checks and CI:
  • Local check scripts: scripts/check-*.sh
  • Workflows: .github/workflows/checks.yml, .github/workflows/validate-tags.yml

---

🚀 Getting Started

yarn install
yarn dev

Open:

http://localhost:3000/en-gb

---

☁️ Netlify Deployment

Build settings:

• Build command: yarn build
• Publish directory: .next

Environment variables:

• GITHUB_TOKEN (recommended)

GitHub Token

Create a token (what is GITHUB_TOKEN) with access to public repos and add it as:

GITHUB_TOKEN=<your_token>

Netlify:

Site Settings → Environment Variables → Add Variable

---

📡 Data Sources

• GitHub REST API (api.github.com)
• NPM Registry (registry.npmjs.org)
• NPM Downloads API (api.npmjs.org)

---

🤝 Contributing

• Issues: github.com/aristobyte/aristo-badges/issues
• Pull requests: github.com/aristobyte/aristo-badges/pulls

---

🔐 Security

• Security overview: github.com/aristobyte/aristo-badges/security
• Report a vulnerability: github.com/aristobyte/aristo-badges/security/advisories/new

---

📜 License

MIT © AristoByte