How to Deploy GitHub Readme Stats on Vercel: Complete Self-Hosting Guide

Deploying GitHub Readme Stats on Vercel requires forking the anuraghazra/github-readme-stats repository, generating a GitHub Personal Access Token with repo and read:user scopes, importing the project into Vercel, and configuring the PAT_1 environment variable before deploying.

When you deploy GitHub Readme Stats on your own Vercel instance, you bypass the rate limits of the public API and gain full control over caching, theming, and access restrictions. This serverless Node.js application renders SVG statistic cards by executing functions defined in api/index.js and api/top-langs.js, automatically detected by Vercel’s zero-config deployment pipeline.

Prerequisites

Before starting, ensure you have the following:

• A GitHub account to fork the repository and generate access tokens.
• A Vercel account (free tier sufficient) linked to your GitHub account.
• A GitHub Personal Access Token (PAT) with appropriate permissions.

Step 1: Fork the Repository

Start by creating your own copy of the source code:

1. Navigate to https://github.com/anuraghazra/github-readme-stats.
2. Click the Fork button in the top-right corner.
3. Select your personal account as the destination.

All subsequent steps operate on your forked copy, which you will sync periodically to receive upstream updates.

Step 2: Generate a GitHub Personal Access Token

The application requires a PAT to fetch repository and user data from the GitHub API:

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic).
2. Click Generate new token (classic).
3. Select the repo and read:user scopes.
4. Copy the generated token immediately (you cannot view it again).

Fine-grained tokens are also supported; ensure they grant equivalent repository and user read permissions. Store this token securely for the next step.

Step 3: Import and Deploy on Vercel

Vercel automatically detects serverless functions in the api/ directory based on the configuration in vercel.json:

1. Log in to vercel.com and click "Add New Project".
2. Select "Import Git Repository" and choose your forked github-readme-stats repository.
3. Vercel will recognize the api/*.js files (such as api/index.js and api/top-langs.js) as serverless functions.
4. Click "Deploy" without changing build settings (the project uses the default Node.js runtime).

The initial deployment will complete, but the endpoints will return errors until you configure the environment variables.

Step 4: Configure Environment Variables

After deployment, navigate to your project’s Settings → Environment Variables in the Vercel dashboard and add the following:

Variable Name	Value	Purpose
PAT_1	Your GitHub token from Step 2	Authenticates API requests to GitHub.
CACHE_SECONDS (optional)	86400 (24 hours)	Overrides default caching duration.
WHITELIST (optional)	your-github-username	Restricts the instance to specific usernames.

Click Save. Vercel will automatically trigger a redeployment. The application reads these variables directly from process.env inside the serverless functions defined in api/index.js.

Step 5: Verify Your Deployment

Test your private instance by constructing a URL with your Vercel project slug:

![My GitHub Stats](https://<project-slug>.vercel.app/api?username=YOUR_GITHUB_USERNAME&show_icons=true)

Replace <project-slug> with your actual Vercel project name and YOUR_GITHUB_USERNAME with your GitHub handle. If configured correctly, the endpoint returns a rendered SVG card instead of a rate-limit error.

Step 6: Embed Cards in Your GitHub Profile

Once verified, add the image to your profile README or repository documentation:

![GitHub Stats](https://<project-slug>.vercel.app/api?username=YOUR_GITHUB_USERNAME&show_icons=true&theme=radical)
![Top Languages](https://<project-slug>.vercel.app/api/top-langs?username=YOUR_GITHUB_USERNAME&layout=compact)

All query parameters documented in the upstream repository (themes, hide options, custom titles) function identically on your self-hosted instance.

Maintenance: Keep Your Fork Updated

To receive bug fixes and new features from the upstream anuraghazra/github-readme-stats repository:

1. Open your fork on GitHub.
2. Click "Sync fork" → "Update branch".
3. Vercel will automatically redeploy when you sync.

Alternatively, configure the pull npm package referenced in the repository documentation to automate this synchronization.

Summary

• Fork the anuraghazra/github-readme-stats repository to your GitHub account.
• Generate a classic PAT with repo and read:user scopes.
• Import the fork into Vercel, which auto-detects functions in api/index.js via vercel.json.
• Configure the PAT_1 environment variable (and optional CACHE_SECONDS or WHITELIST).
• Deploy and verify the endpoint at https://<project-slug>.vercel.app/api.
• Embed the SVG URLs in your GitHub profile README.
• Sync your fork periodically to stay current with upstream improvements.

Frequently Asked Questions

Do I need a paid Vercel plan to run GitHub Readme Stats?

No. The free tier is sufficient for personal use. The application runs as serverless functions within Vercel’s hobby tier limits. However, heavy traffic may trigger rate limits, at which point you might consider upgrading or implementing the WHITELIST environment variable to restrict usage.

Why does my deployment show a "Rate Limit" error?

This occurs when the PAT_1 environment variable is missing or invalid. The application requires a valid GitHub Personal Access Token to authenticate API requests. Verify that you have added the variable in Vercel’s dashboard and redeployed the project after saving.

Can I use fine-grained personal access tokens instead of classic tokens?

Yes. Fine-grained tokens are supported as long as they grant read access to repository contents and user profile data. Ensure the token has permissions equivalent to the repo and read:user scopes required by the classic token configuration.

How do I customize the cache duration for my stats cards?

Set the CACHE_SECONDS environment variable in your Vercel project settings. The value should be an integer representing seconds (e.g., 1800 for 30 minutes or 86400 for 24 hours). After saving, Vercel will redeploy the application with the new caching logic defined in the source code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}