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.
?user=octocat
)Now the framework includes complete typing for better development and intelligent autocompletion.
Developer passionate about Open Source, data, and tools that empower the technical community.
best practices
.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.
Explore forks, stars, issues, pull requests, and contributors in any public repository.
Get details like followers, bio, most used languages, and top repositories of any user.
Use charts with Chart.js, D3.js, or ECharts to create custom and responsive views of the data.
Consume GitHub data using reusable modules, with full support for modern TypeScript and JavaScript.
Filter data by language, dates, contributors, commit types, or topics for precise analyses.
The framework is designed to make programming easier and safer.
// 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
});
import { GitHubRepoService } from 'github-framework';
const repoService = new GitHubRepoService();
repoService.getUserRepos('octocat').then(repos => {
repos.forEach(repo => console.log(repo.name));
});
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']
}]
}
});
});
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.
GitHub REST API
encapsulated in reusable modules.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) |
To get started with the GitHub Explorer Framework, you can install it using npm
, yarn
, or import it via CDN
directly in the browser.
npm install github-framework
yarn add github-api-framework
<script src="https://cdn.jsdelivr.net/npm/github-api-framework@latest/dist/github.min.js"></script>
import { GitHubExplorer } from 'github-api-framework'
const { GitHubExplorer } = require('github-api-framework')
window.GitHubExplorer
>= 18.x
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
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:
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).
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
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
});
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.
window.explorer
The GitHub Explorer Framework allows direct connection to GitHub's public API to search for information about users, repositories, organizations, contributions and much more.
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).
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.
const explorer = new GitHubExplorer(); // Without token
explorer.getUser("octocat").then(user => {
console.log(user.name, user.bio);
});
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.
Free GitHub users can generate unlimited tokens, and expired tokens can be renewed at any time.
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.
GitHubUser
β Works with user dataGitHubRepo
β Queries and filters repositoriesGitHubOrg
β Manages organization dataGitHubLang
β Detects and analyzes languagesGitHubStats
β Aggregated statistics for dashboardsGitHubActivity
β Histories of commits, events, and PRsimport { 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);
GitHubService
GitHubExplorer
β Central instance with global configs (token, cache, headers)GitHubRequest
β Makes direct requests to the API (fetch + error handlers)GitHubCache
β Stores temporary responses locallyGitHubService
β Base for all modules (inherited by GitHubUser
, etc)import { GitHubService } from 'github-framework';
class GitHubPinnedRepos extends GitHubService {
async getPinnedRepos(username) {
return this.request(`/users/${username}/repos?sort=pinned`);
}
}
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
.
Chart.js
installed via CDN or npm<canvas>
to render the chartsGitHubExplorer
to fetch dataThis 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');
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');
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
{
javascript: 12,
python: 4,
html: 3,
css: 2
}
?user=nome
in the URLDataTables
or D3.js
for more control
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.
5,000 requests per hour
import { GitHubExplorer } from 'github-api-framework';
const explorer = new GitHubExplorer({
token: 'ghp_yourTokenHere'
});
Go to github.com/settings/tokens and click on "Generate new token (classic)".
public_repo
scope if you want to access only public repositoriesimport { 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);
}
403: API rate limit
β missing or invalid token401: Bad credentials
β expired or incorrect tokenundefined is not a function
β forgetting to properly instantiate GitHubExplorer.env
) for tokens in Node.js, Next.js, or Astro# .env
GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXX
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.
npm install chart.js
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'],
}]
}
});
}
<canvas id="grafico" width="400" height="400"></canvas>
You can extend this usage with line, bar, radar charts, and more!
To make the most of the GitHub Explorer Framework with stability, security, and performance, follow these best practices:
user.js
, repos.js
, and charts.js
Factory
pattern to instantiate users/reposmedia queries
and flex/grid
console.table()
to visualize API objectsWhen using the GitHub Explorer Framework, properly handling errors is essential to ensure a good user experience and avoid unexpected failures.
403 Forbidden
β Anonymous request limit exceeded404 Not Found
β User or repository not found500 Internal Server Error
β Problem with GitHub servers
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.');
}
}
try/catch
blocks for all asynchronous callsstatus
of the error to handle different casesThe GitHub Explorer Framework is highly optimized but is subject to the limitations imposed by the GitHub API itself.
60 req/hour
5,000 req/hour
per token
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.