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.