RepoWidget

The Problem

Developers and organizations frequently want to showcase their GitHub repositories on portfolios, documentation, or marketing pages. The usual approaches all have painful trade-offs:

RepoWidget eliminates all three. Drop in the script, call one function — repositories appear live, always current, with zero maintenance.

<!-- Before: static, stale, hand-maintained -->
<div class="repo-card">
  <h3>my-cool-project</h3>
  <p>A tool I made — ★ 42 forks 7</p> <!-- already wrong -->
</div>

<!-- After: live data, always correct -->
<div id="repos"></div>
<script src="https://cdn.jsdelivr.net/npm/repowidget/dist/repoWidget.min.js"></script>
<script>
  createRepoWidget({ username: 'your-username', containerId: 'repos' });
</script>

Features

How It Works

RepoWidget is a thin layer over the GitHub REST API v3. On each page load it checks localStorage for a valid cache; on a miss (or after 24 hours) it fires a conditional request with an ETag header so unchanged data costs zero bytes. The resulting JSON is filtered, sorted, and rendered in a single innerHTML write.

1. 1 Cache check — LocalStorage is queried for an unexpired entry. If one exists, rendering skips straight to step 4.
2. 2 API fetch — A Fetch request is sent to api.github.com/users/{'{'}username{'}'}/repos, optionally with a stored ETag to receive a 304 instead of redundant data.
3. 3 Filter & sort — Forks, excluded slugs, and archived repos are dropped. The remainder is sorted by stars, forks, name, size, or updated and capped at maxRepos.
4. 4 Render — Repository cards are generated and injected into the container in a single DOM write. Language badges receive automatic color coding.

Configuration

Pass an options object to createRepoWidget(). Only username and containerId are required.

Core

Layout

Styling

Callbacks

Code Examples

Vanilla HTML — CDN

<div id="repos"></div>

<script src="https://cdn.jsdelivr.net/npm/repowidget/dist/repoWidget.min.js"></script>
<script>
  createRepoWidget({
    username: 'your-username',
    containerId: 'repos',
    maxRepos: 6,
    sortBy: 'stars',
    exclude: ['your-username.github.io'],
    columns: { mobile: 1, tablet: 2, desktop: 3 }
  });
</script>

React

import { useEffect } from 'react';
import { createRepoWidget } from 'repowidget';

function RepoDisplay() {
  useEffect(() => {
    createRepoWidget({ username: 'your-username', containerId: 'repos', maxRepos: 6 });
  }, []);

  return <div id="repos"></div>;
}

Custom style override

createRepoWidget({
  username: 'your-org',
  containerId: 'oss-repos',
  sortBy: 'updated',
  forked: false,
  cardStyles: {
    backgroundColor: '#0f1117',
    borderRadius: '12px',
    border: '1px solid #30363d',
    boxShadow: '0 4px 12px rgba(0,0,0,0.4)'
  },
  textStyles: {
    titleColor: '#58a6ff',
    descriptionColor: '#8b949e'
  },
  onLoad: (repos) => console.log(`Rendered ${repos.length} repos`)
});

How It Compares

RepoWidget specializes. It doesn't try to be a charting library or a full design system.

Get Started in Minutes

Install via npm or drop the CDN link directly into your HTML. No bundler, no config file, no component architecture to learn.

# npm
npm install repowidget

# or via CDN
https://cdn.jsdelivr.net/npm/repowidget/dist/repoWidget.min.js
https://unpkg.com/repowidget/dist/repoWidget.min.js