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.

• ✅ Single instance for the entire application
• ✅ Can be stored in global context, like window.explorer
• ✅ Reusable in any modern framework (React, Vue, etc)

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.

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:

• GitHubUser – Works with user data
• GitHubRepo – Queries and filters repositories
• GitHubOrg – Manages organization data
• GitHubLang – Detects and analyzes languages
• GitHubStats – Aggregated statistics for dashboards
• GitHubActivity – Histories of commits, events, and PRs

🛠️ 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

• 🔄 Simple maintenance: each module can evolve independently
• ⚡ Performance: use only the modules you need
• 🌱 Extensibility: create your own modules based on GitHubService
• 🧪 Ease of testing: modules are independent

🏗️ Internal Architecture (Layers)

• GitHubExplorer – Central instance with global configs (token, cache, headers)
• GitHubRequest – Makes direct requests to the API (fetch + error handlers)
• GitHubCache – Stores temporary responses locally
• GitHubService – Base for all modules (inherited by GitHubUser, etc)

💡 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:

• 💼 The architecture follows SOLID principles
• 📦 Modules are compatible with tree-shaking
• 🧱 Ready-to-use support for SPA, SSR, and JAMStack

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

• Chart.js installed via CDN or npm
• DOM with <canvas> to render the charts
• Calls with the GitHubExplorer to fetch data

📌 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:

• 📌 Visualization of collaborators by repository
• 📈 Comparison of stars/forks between projects
• 📆 Weekly/monthly activity of the user
• 📂 NNumber of repositories by language

📁 Data response pattern:

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

🧠 Tip for dashboards:

• 🔁 Update data by typing ?user=nome in the URL
• 📲 Make the dashboard responsive with media queries
• ⚙️ Combine with libraries like DataTables 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.

📌 Advantages of authentication:

• 🚀 Increases the limit to up to 5,000 requests per hour
• 🛡️ Prevents blocks due to excessive access (403 Rate Limit)
• 🔧 Allows access to private data (if authorized)

🔧 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:

• 🔒 Check only the public_repo scope if you want to access only public repositories
• 🧼 NEVER expose the token directly in the frontend in production
• 🔁 Revoke old tokens that are no longer in use

📦 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

• 403: API rate limit — missing or invalid token
• 401: Bad credentials — expired or incorrect token
• undefined is not a function — forgetting to properly instantiate GitHubExplorer

🔒 Security

• ⚙️ In client-side apps, use tokens only for testing
• 📦 In production, protect the token in the backend and create an intermediary API
• 👨‍💻 Always use environment variables (.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.

📦 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:

• D3.js
• ECharts
• Highcharts
• ApexCharts

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

📁 Code Organization

• 🚀 Separate responsibilities into files like user.js, repos.js, and charts.js
• ✅ Use async functions whenever consuming the API

🔐 Security

• 🔒 Avoid exposing tokens in public frontends
• 💼 In production environments, use a backend API as a proxy

⚙️ Performance

• 📦 Cache static API responses (users, languages, etc.)
• 🔁 Reduce duplicate calls by using debounce/throttle on inputs

📦 Design Patterns

• 🏗️ Use the Factory pattern to instantiate users/repos
• 🧱 Keep the interface decoupled from the network logic
''

📊 Visualization

• 🎨 Make the view responsive with media queries and flex/grid
• 🕶️ Dark mode: respect the user's theme for better accessibility

🧪 Testing and Debugging

• 🐞 Use console.table() to visualize API objects
• 🧪 Use Jest/Vitest for testing transformation functions

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

📌 Common Possible Errors

• 403 Forbidden — Anonymous request limit exceeded
• 404 Not Found — User or repository not found
• 500 Internal Server Error — Problem with GitHub servers

💡 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

• Use try/catch blocks for all asynchronous calls
• Check the status of the error to handle different cases
• Provide friendly feedback and instructions to the end user
• Log errors in development environments for debugging

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

🚦 GitHub REST API Limits

• 🔒 Anonymous requests: up to 60 req/hour
• 🔐 Authenticated requests: up to 5,000 req/hour per token
• ⚙️ GraphQL requests: based on complexity cost, not just quantity

🚀 Tips for High Performance

• Use personal tokens to increase the limit
• Avoid unnecessary repeated calls
• Cache static responses (such as language data or avatar)
• Prefer the REST API for simple and direct data

📚 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.

The GitHub Explorer Framework will soon expand to support GitLab API integration in version 1.1.0, providing a unified interface to work with both platforms.

📦 Key Components

🚀 Basic Usage Example

const config = {
  username: 'yourUsername',
  token: 'yourAccessToken',
  baseUrl: 'https://gitlab.com/api/v4'
};

const userService = new GitLabUserService(config);
await userService.loadUserData();
console.log(userService.renderProfile());
        

🔑 Authentication

Similar to GitHub, you'll need a GitLab Personal Access Token:

const explorer = new GitLabExplorer({
  token: "glpat-yourTokenHere",
  baseUrl: "https://gitlab.com/api/v4"
});
        

📊 Data Structure Examples

{
  "avatarUrl": "",
  "name": "",
  "bio": "",
  "followers": 0,
  "following": 0,
  "publicRepos": 0,
  "stats": {}
}
            

{
  "id": "",
  "name": "",
  "description": "",
  "language": "",
  "stars": 0,
  "forks": 0,
  "updatedAt": "",
  "url": ""
}
            

The GitHub Explorer Framework provides complete TypeScript support with well-defined interfaces for all API responses and formatted data structures.

interface GitHubConfig {
  githubUsername: string;
  githubToken?: string;  // Optional authentication token
}
            

interface Repository {
  id: number;
  name: string;
  full_name: string;
  private: boolean;
  html_url: string;
  description: string | null;
  language: string | null;
  stargazers_count: number;
  forks_count: number;
  updated_at: string;
}

interface FormattedRepo {
  name: string;
  description: string;
  language: string;
  stars: number;
  forks: number;
  updatedAt: string;
  url: string;
}
            

type ActivityType = 
  | 'PushEvent'
  | 'CreateEvent'
  | 'PullRequestEvent'
  | 'IssuesEvent';

interface Activity {
  id: string;
  type: ActivityType;
  repo: { name: string };
  created_at: string;
  payload: {
    action?: string;
    ref?: string;
  };
}

interface FormattedActivity {
  text: string;
  icon: string;  // Font Awesome icon class
  date: string;  // Human-readable format
}
            

interface UserProfile {
  login: string;
  name: string | null;
  bio: string | null;
  public_repos: number;
  followers: number;
  following: number;
}

interface FormattedProfile {
  avatarUrl: string;
  name: string;
  bio: string;
  followers: number;
  following: number;
  publicRepos: number;
}
            

interface Helpers {
  getAuthHeaders(token?: string | null): Record<string, string>;
  formatFileSize(bytes: number): string;
  formatDate(date: Date | string): string;
}

interface Formatters {
  formatCommitMessage(message: string): string;
  formatDateTime(date: Date | string): string;
}
            

import { GitHubExplorer } from 'github-framework';

const config: GitHubConfig = {
  githubUsername: 'octocat',
  githubToken: process.env.GITHUB_TOKEN
};

async function getUserRepos(): Promise<FormattedRepo[]> {
  const explorer = new GitHubExplorer(config);
  return await explorer.getUserRepos(config.githubUsername);
}