🧭 What is the GitHub Explorer Framework?

GitHub Explorer Framework is a visual, analytical and modular framework built on top of GitHubAPIHelper, created to explore, visualize and understand public GitHub data.

It provides a layer of dynamic dashboard that allows developers, analysts, open-source maintainers, and educators to analyze information from profiles, repositories, languages, and contributions with high precision and ease.

It is possible to integrate it with libraries such as Chart.js, D3.js and DataTables to create responsive charts, reports, and visualizations optimized for SEO.

  • πŸ“¦ Modular and expandable with pure JavaScript or modern frameworks
  • πŸ“Š Full support for interactive charts
  • πŸ” Friendly URLs and configurable by query string (ex: ?user=octocat)
  • πŸš€ Optimized for use as a single page application or embedded

πŸš€ What's new in the version 1.1.0

Official TypeScript Support!

Now the framework includes complete typing for better development and intelligent autocompletion.

v2.0+ New
Foto do autor

πŸ‘¨β€πŸ’» Created by @LuisOtavio13

Developer passionate about Open Source, data, and tools that empower the technical community.

πŸ€” Why use the GitHub Explorer Framework?

  • πŸ” Visualize complex data in a simple and interactive way.
  • βš™οΈ Extendable with JavaScript, Chart.js, and REST APIs.
  • πŸš€ Great for dashboards, reports, and technical education.
  • 🧩 Based on reusable modules with a focus on best practices.
  • πŸ“ˆ Allows monitoring of activity, languages, and contributions of any user or public repository.

The GitHub Explorer was born out of the need for a practical and reusable solution for frequent analyses of GitHub profiles, especially in community contexts, bootcamps, open-source teams, and technical mentoring.

πŸš€ Main Features

Repository Analysis

Explore forks, stars, issues, pull requests, and contributors in any public repository.

Profile Visualization

Get details like followers, bio, most used languages, and top repositories of any user.

Interactive Dashboard

Use charts with Chart.js, D3.js, or ECharts to create custom and responsive views of the data.

API Modular

Consume GitHub data using reusable modules, with full support for modern TypeScript and JavaScript.

Advanced Filters

Filter data by language, dates, contributors, commit types, or topics for precise analyses.

Easy to Use

The framework is designed to make programming easier and safer.

πŸ“˜ Quick Usage Examples

πŸ” Search for user information


        // Importing the main module
        import { GitHubUserService } from 'github-framework';

        // Creating instance and fetching user data
        const userService = new GitHubUserService();
        userService.getUser('octocat').then(user => {
        console.log(user.name);       // The Octocat
        console.log(user.publicRepos); // 8
        });
            

πŸ“¦ List user repositories


        import { GitHubRepoService } from 'github-framework';

        const repoService = new GitHubRepoService();
        repoService.getUserRepos('octocat').then(repos => {
        repos.forEach(repo => console.log(repo.name));
        });
            

πŸ“Š View used languages with graph


        import { GitHubLanguageService } from 'github-framework';
        import Chart from 'chart.js/auto';

        const langService = new GitHubLanguageService();
        langService.getLanguagesByUser('octocat').then(data => {
        new Chart(document.getElementById('grafico'), {
            type: 'doughnut',
            data: {
            labels: Object.keys(data),
            datasets: [{
                data: Object.values(data),
                backgroundColor: ['#f1e05a', '#563d7c', '#3572A5']
            }]
            }
        });
        });
            

🧩 Architecture and Technologies

The GitHub Explorer Framework is designed to be modular, extensible, and easy to integrate with other analytical and visual tools. It follows the principles of Clean Architecture and Separation of Concerns.

  • πŸ”§ Service Layer: Communication with the GitHub REST API encapsulated in reusable modules.
  • 🎨 Presentation Layer: Dynamic dashboards, widgets, reusable HTML/CSS components.
  • πŸ“Š Analysis Layer: Data grouping, counting by author, language, period, and event type.
  • πŸ” SPA Support: Can be used as a Single Page Application with navigation via pure JavaScript.

The architecture is divided into the following main modules:

Module Responsibility Technologies
UserService Fetch and process user profile data Fetch API, JS, GitHub API v3
RepoService List and filter repositories Axios, JSON, Lodash
CommitService Collect and analyze commits by author/date Date-fns, Chart.js
LanguageService Map and display languages D3.js, REST API
ActivityService Analyze user events and interactions Webhooks GitHub, Vue/React (optional)

Changelog

1.1.0 Shortly NOT RELEASED
  • ADDED Fallback data system when API fails
  • ADDED GraphQL support for contributions
  • FIXED Error handling with detailed messages
  • UPDATED TypeScript definitions for all services
1.0.0 2025-07-19
  • ADDED Initial release: Web dashboard UI
  • ADDED Modular service classes (Users, Repos, Commits)
  • ADDED Example usage and Jest tests

πŸ“¦ Installing the GitHub Explorer Framework

To get started with the GitHub Explorer Framework, you can install it using npm, yarn, or import it via CDN directly in the browser.


🧰 Installation via NPM

npm install github-framework

🧰 Installation via Yarn

yarn add github-api-framework

🌐 Usage with CDN

<script src="https://cdn.jsdelivr.net/npm/github-api-framework@latest/dist/github.min.js"></script>

πŸš€ Importing into the Project

  • ESModules: import { GitHubExplorer } from 'github-api-framework'
  • CommonJS: const { GitHubExplorer } = require('github-api-framework')
  • Global (CDN): window.GitHubExplorer

πŸ§ͺ Prerequisites

  • βœ… Node.js >= 18.x
  • βœ… Modern browser (Chrome, Edge, Firefox)
  • βœ… Code editor (VSCode, WebStorm, etc.)

πŸ” Authentication with Token (optional)

To avoid anonymous request limits on the GitHub API, you can use a personal access token:


            const explorer = new GitHubExplorer({
            token: "ghp_seuTokenAqui"
            });
                

Generate your token at: github.com/settings/tokens


🧯 Common Errors

  • ❌ 403: API rate limit β€” add a token
  • ❌ "GitHubExplorer is not defined": CDN script not loaded correctly
  • ❌ Import error: check if your bundler supports ESModules

πŸ“Œ Observations

  • πŸ’‘ Full support for modern frameworks: React, Vue, Svelte, Next.js, Astro
  • πŸ› οΈ TypeScript support will be included in future versions
  • πŸ”§ Open source licensed under GPL

Our Products

Electronics
Clothing
Accessories

Services

Contact

πŸ”§ Instantiating the Explorer

To start using the GitHub Explorer Framework, the first step is to instantiate the main object of the library: GitHubExplorer.

You can do this simply, directly in your JavaScript code:

πŸ“¦ Basic Mode (no authentication)

const explorer = new GitHubExplorer();

This mode allows you to explore public GitHub data, but is subject to the API's anonymous request limits (60 requests per hour).

πŸ” Authentication Mode (personal token)


    const explorer = new GitHubExplorer({
    token: "ghp_yourTokenHere"
    });
        

Using a token is highly recommended to avoid limitations. You can generate a token at: github.com/settings/tokens

🎯 Advanced Mode (with extra settings)


    const explorer = new GitHubExplorer({
    token: "ghp_yourTokenHere",
    cache: true,           // activates local cache
    log: true,             // shows logs in console
    baseUrl: "https://api.github.com" // custom endpoint if needed
    });
        

πŸ”Ž Checking the instance


    console.log(explorer);
    // Should show available methods: getUser, getRepos, getLanguages, etc.
        

Once the instance is ready, you can use all the framework's features, such as searching users, repositories and GitHub statistics.

πŸ“‘ Connecting to GitHub API

The GitHub Explorer Framework allows direct connection to GitHub's public API to search for information about users, repositories, organizations, contributions and much more.

βœ… Instantiating with authentication (recommended)


    import { GitHubExplorer } from 'github-framework';

    const explorer = new GitHubExplorer({
    token: "ghp_yourTokenHere"
    });
        

If you choose not to use an authentication token, the framework will still work. However, GitHub's API will apply stricter request limits (60 per hour).

πŸ”’ Where can I get my token?

Go to github.com/settings/tokens, click on "Generate new token", select the desired scopes (read-only for basic use) and generate your personal token.

πŸ§ͺ Example without authentication


    const explorer = new GitHubExplorer(); // Without token
    explorer.getUser("octocat").then(user => {
    console.log(user.name, user.bio);
    });
        

πŸ›‘ Avoid exposing tokens on the frontend!

In production projects, store the token in environment variables and use it on the backend. Public tokens in the browser can be easily captured by malicious users.

πŸ“˜ Tip: Free GitHub tokens

Free GitHub users can generate unlimited tokens, and expired tokens can be renewed at any time.

🧩 Modular Structure

The GitHub Explorer Framework is developed with a modular architecture and service-oriented approach, providing scalability, reusability, and code clarity. Each functionality is separated into independent modules, making selective use and integration with any modern stack easier.

πŸ“¦ Main available modules:

πŸ› οΈ Example of modular usage

import { GitHubExplorer, GitHubUser, GitHubRepo } from 'github-framework';

    const explorer = new GitHubExplorer({ token: "ghp_yourTokenHere" });

    const user = new GitHubUser(explorer);
    const repo = new GitHubRepo(explorer);

    user.getProfile('octocat').then(console.log);
    repo.listByUser('octocat').then(console.log);

πŸ” Advantages of modularity

πŸ—οΈ Internal Architecture (Layers)

πŸ’‘ Example of custom extension:

import { GitHubService } from 'github-framework';

    class GitHubPinnedRepos extends GitHubService {
    async getPinnedRepos(username) {
        return this.request(`/users/${username}/repos?sort=pinned`);
    }
    }

πŸ“Œ Observations:

πŸ“Š Data Visualization

The GitHub Explorer Framework makes it easy to create interactive and visual dashboards using libraries like Chart.js, D3.js, Recharts, or any other based on SVG or Canvas.

πŸ“¦ Prerequisites

πŸ“Œ Example 1 β€” Most used languages by a user (Chart.js)

This chart shows the distribution of languages across all public repositories of a user.

<canvas id="langChart" width="400" height="400"></canvas>
import { GitHubExplorer, GitHubLang } from 'github-framework';
    import Chart from 'chart.js/auto';

    const explorer = new GitHubExplorer({ token: 'ghp_seuTokenAqui' });
    const langService = new GitHubLang(explorer);

    async function gerarGraficoLinguagens(usuario) {
    const dados = await langService.getLanguagesByUser(usuario);

    const labels = Object.keys(dados);
    const valores = Object.values(dados);

    new Chart(document.getElementById('langChart'), {
        type: 'doughnut',
        data: {
        labels,
        datasets: [{
            label: 'Linguagens',
            data: valores,
            backgroundColor: ['#3b82f6', '#22c55e', '#eab308', '#ef4444'],
        }]
        }
    });
    }

    gerarGraficoLinguagens('octocat');

πŸ“ˆ Example 2 β€” Activity by Month (Commits / PRs)

This shows a bar chart with the number of events per month.

<canvas id="atividadeChart"></canvas>
import { GitHubActivity } from 'github-api-framework';

    const activity = new GitHubActivity(explorer);

    async function gerarGraficoAtividade(usuario) {
    const eventos = await activity.getMonthlyActivity(usuario);
    const meses = Object.keys(eventos);
    const valores = Object.values(eventos);

    new Chart(document.getElementById('atividadeChart'), {
        type: 'bar',
        data: {
        labels: meses,
        datasets: [{
            label: 'Eventos GitHub',
            data: valores,
            backgroundColor: '#6366f1'
        }]
        }
    });
    }

    gerarGraficoAtividade('octocat');

🌐 Tip: CDN for Chart.js

<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>

πŸ’‘ Other visualization possibilities:

πŸ“ Data response pattern:

{
    javascript: 12,
    python: 4,
    html: 3,
    css: 2
    }

🧠 Tip for dashboards:

πŸ” Token Authentication

GitHub imposes limits on anonymous requests (without authentication), usually 60 requests per hour per IP. For more robust applications, the use of a Personal Access Token (PAT) is recommended.

πŸ“Œ Advantages of authentication:

πŸ”§ Instantiating with Token

import { GitHubExplorer } from 'github-api-framework';

    const explorer = new GitHubExplorer({
    token: 'ghp_yourTokenHere'
    });

πŸ“ Where to generate the token?

Go to github.com/settings/tokens and click on "Generate new token (classic)".

🧠 Tips for generation:

πŸ“¦ Complete example of authenticated usage

import { GitHubExplorer, GitHubUser } from 'github-api-framework';

    const explorer = new GitHubExplorer({
    token: 'ghp_XXXXXXXXXXXXXXXXXXXX'
    });

    const user = new GitHubUser(explorer);

    async function carregarPerfil(nome) {
    const perfil = await user.getUser(nome);
    console.log(perfil);
    }

⚠️ Common errors

πŸ”’ Security

# .env
    GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXX

πŸ“Š Integrations with Chart.js

The GitHub Explorer Framework is designed to work with visualization libraries like Chart.js, allowing you to easily transform API data into interactive and beautiful charts.

πŸ“¦ Install Chart.js

npm install chart.js

πŸ“ˆ Example: Visualizing languages of a repository

import { GitHubExplorer, GitHubRepo } from 'github-framework';
    import Chart from 'chart.js/auto';

    const explorer = new GitHubExplorer();
    const repo = new GitHubRepo(explorer);

    async function mostrarLinguagens() {
    const langs = await repo.getRepoLanguages('octocat/Hello-World');

    const labels = Object.keys(langs);
    const data = Object.values(langs);

    new Chart(document.getElementById('grafico'), {
        type: 'doughnut',
        data: {
        labels,
        datasets: [{
            label: 'Bytes por linguagem',
            data,
            backgroundColor: ['#4e79a7', '#f28e2b', '#e15759', '#76b7b2'],
        }]
        }
    });
    }

πŸ–ΌοΈ HTML for the chart

<canvas id="grafico" width="400" height="400"></canvas>

You can extend this usage with line, bar, radar charts, and more!

🎯 Other compatible libraries:

πŸ§ͺ Best Practices

To make the most of the GitHub Explorer Framework with stability, security, and performance, follow these best practices:

πŸ“ Code Organization

πŸ” Security

βš™οΈ Performance

πŸ“¦ Design Patterns

πŸ“Š Visualization

πŸ§ͺ Testing and Debugging

🚨 Error Handling with Examples

When using the GitHub Explorer Framework, properly handling errors is essential to ensure a good user experience and avoid unexpected failures.

πŸ“Œ Common Possible Errors

πŸ’‘ How to Handle Errors in the Explorer Instance


        const explorer = new GitHubExplorer();

        try {
        const user = await explorer.getUser('octocat');
        console.log(user);
        } catch (error) {
        console.error('Erro ao buscar usuΓ‘rio:', error.message);

        if (error.status === 403) {
            alert('VocΓͺ excedeu o limite de requisiΓ§Γ΅es da API. Use um token!');
        } else if (error.status === 404) {
            alert('UsuΓ‘rio nΓ£o encontrado. Verifique o nome digitado.');
        }
        }
            

βœ… Best Practices

πŸ“ˆ API Performance and Limitations

The GitHub Explorer Framework is highly optimized but is subject to the limitations imposed by the GitHub API itself.

🚦 GitHub REST API Limits

πŸš€ Tips for High Performance

πŸ“š Example of manual caching


    const cache = new Map();

    async function getUser(username) {
    if (cache.has(username)) return cache.get(username);

    const user = await explorer.getUser(username);
    cache.set(username, user);
    return user;
    }
        

The conscious use of the API is essential for production applications, especially when displaying real-time data for multiple users.