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

> Deploy GitHub Readme Stats on Vercel easily. Follow our step by step guide to self-host this popular project and enhance your GitHub profile. Get started now.

- Repository: [Anurag Hazra/github-readme-stats](https://github.com/anuraghazra/github-readme-stats)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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`](https://github.com/anuraghazra/github-readme-stats/blob/main/api/index.js) and [`api/top-langs.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/api/index.js) and [`api/top-langs.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/api/index.js).

## Step 5: Verify Your Deployment

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

```markdown
![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:

```markdown
![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`](https://github.com/anuraghazra/github-readme-stats/blob/main/api/index.js) via [`vercel.json`](https://github.com/anuraghazra/github-readme-stats/blob/main/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.