🚀 github-portfolio-fetcher

A lightweight, zero-dependency, browser-optimized TypeScript library to fetch repository details directly from the GitHub API. Supercharge your portfolio website with dynamic GitHub data, custom metadata, and intelligent local caching.

✨ Features

• 📦 Zero Runtime Dependencies — Keeps your production bundle light.
• ⚡ Parallel Batch Fetching — Retrieves multiple repositories concurrently using Promise.all.
• 💾 Smart Local Caching — Stores API results in localStorage with a 1-hour expiration time to stay clear of rate limits.
• 🖼️ Fallback Preview Images — Extracts preview images from meta.json or parses the first markdown image in your README.md.
• 📝 Custom Project Metadata — Parses extra information from meta.json (such as technology stacks, features, category, and live preview URLs).
• 🧩 Strict TypeScript Types — Fully typed API out of the box.

📥 Installation

npm install github-portfolio-fetcher

🚀 Quick Start

Here is how you can use the library in your portfolio site:

import { fetchRepos } from 'github-portfolio-fetcher';

// Define the repositories you wish to fetch
const repositories = [
  { owner: 'username', repo: 'repository' },
  { owner: 'username', repo: 'repository-2' }
];

try {
  // Fetch details
  const projects = await fetchRepos(repositories);
  console.log(projects);
} catch (error) {
  console.error('Failed to retrieve project details:', error);
}

🛠️ Metadata Format (meta.json)

To customize your project display with extra details that the GitHub API doesn't provide out of the box, place a meta.json file in the root of your repository.

The supported format is as follows:

{
  "title": "Daniel's Personal Portfolio",
  "shortDescription": "A sleek, modern portfolio website built using React & Vite.",
  "longDescription": "This project showcases my profile, achievements, and work experience. It leverages automated fetching from GitHub and displays interactive visual charts.",
  "imageUrls": [
    "https://example.com/assets/portfolio-preview-1.png",
    "https://example.com/assets/portfolio-preview-2.png"
  ],
  "liveUrl": "https://sipangkar-daniel.dev",
  "features": [
    "Responsive sleek dark mode UI",
    "Interactive repository showcase cards",
    "Real-time GitHub statistics integration"
  ],
  "documentationUrl": "https://docs.sipangkar-daniel.dev" 
}

[!TIP] Backward Compatibility: If you have an older project structure using "imageUrl": "string", the library automatically wraps it into the imageUrls array as [imageUrl].

📚 API Reference

fetchRepos(repos: RepoInput[]): Promise<RepoOutput[]>

Retrieves data for an array of repositories. Matches the input ordering exactly.

Input Structure (RepoInput)

export interface RepoInput {
  owner: string; // The username or organization name
  repo: string;  // The repository name
}

Output Structure (RepoOutput)

export interface RepoOutput {
  // Default GitHub repository details
  name: string;                // Repository name
  fullName: string;            // Format: "owner/repo"
  description: string;         // Repository description (defaults to empty string)
  htmlUrl: string;             // GitHub repository HTML URL
  stars: number;               // Total stars
  forks: number;               // Total forks
  language: string;            // Primary language (defaults to "Unknown")
  topics: string[];            // List of repository topics

  // Resolved metadata & images
  imageUrls?: string[];        // Array of preview image URLs
  liveUrl?: string;            // Live project website URL
  
  // Custom metadata (parsed from meta.json if available)
  title?: string;              // Project display title
  shortDescription?: string;   // Short summary
  longDescription?: string;    // Detailed description
  technologies?: string[];     // Technology stack names
  features?: string[];         // Core features checklist
  year?: string;               // Release or build year
  category?: string;           // Project category
  status?: string;             // Project status (e.g. Active, Archive)
  documentationUrl?: string;   // Link to docs

  // Raw Response Payload
  raw: any;                    // Complete raw response object from the GitHub API
}

clearCache(): void

Invalidates and deletes all cached repository metadata from localStorage.

🔍 Image & Metadata Resolution Priority

When fetching details, preview images are resolved using the following order:

1. meta.json at root level (Priority 1): Looks for imageUrls or imageUrl inside the meta.json file.
2. README.md (Priority 2): If meta.json is not found or has no images, parses the repository's README.md content for the first markdown image syntax: ![Alt Text](https://example.com/image.png). This URL will be placed in the imageUrls array as [imageUrl].

💾 Caching Strategy

The library automatically manages client-side caching to respect GitHub's API rate limits (60 requests/hour for unauthenticated users):

• Each repository's output is saved to localStorage under the key github-fetcher-${owner}-${repo}.
• Cache entry has a TTL (Time-To-Live) of 1 hour.
• Works safely across Server-Side Rendered (SSR) environments by verifying window-level support before interacting with the cache.

👩‍💻 Local Development

1. Install Dependencies:

   npm install

2. Build Library:

   npm run build

3. Local Testing via npm link:

   npm link
      
   # In your client application directory:
   npm link github-portfolio-fetcher

📄 License

MIT