Pixel Profile: Generate pixel art profiles from your GitHub data

🚀 What's New

CRT Stats Card

A brand new retro CRT-style stats card with:

• Authentic CRT monitor frame with curved screen effect
• Scanlines, RGB shift, and phosphor glow effects
• Available via GitHub Actions with crt_outputs parameter

GitHub Actions Integration

Pre-generate your stats cards with GitHub Actions for:

• Instant visibility, even in poor network conditions
• Faster loading times for your GitHub profile

Quick Start: Check out LuciNyan's Profile for an example setup.

🎉 Halid created an awesome UI for pixel-profile!

Try it out: https://pixel-profile-generator.vercel.app

Overview

You can easily generate a Github stats card with default styling using the following link:

<!--Replace <username> with your own GitHub username.-->
https://pixel-profile.vercel.app/api/github-stats?username=<username>

Of course, you can customize the styling to better suit your preferences. For example, here is a stats card designed for GitHub's Dark Theme:

https://pixel-profile.vercel.app/api/github-stats?username=<username>&screen_effect=true&theme=rainbow

This is what it looks like in a README:

If you want to include a GitHub stats card in your own README file and have it display the appropriate card for both the light and dark themes on GitHub, you can refer to the following configuration and configure your preferred theme, or fully customize elements like color, background, screen effects, etc:

<picture decoding="async" loading="lazy">
  <source media="(prefers-color-scheme: light)" srcset="https://pixel-profile.vercel.app/api/github-stats?username=<username>&theme=summer">
  <source media="(prefers-color-scheme: dark)" srcset="https://pixel-profile.vercel.app/api/github-stats?username=<username>&screen_effect=true&theme=blue_chill">
  <img alt="github stats" src="https://pixel-profile.vercel.app/api/github-stats?username=<username>&theme=summer">
</picture>

Here is a ready-made example configuration you can reference if you need inspiration for your own config.

Documentation

Themes

Below are some prebuilt themes to get started. However, cards are fully customizable by passing in background and color props. Feel free to ditch the premade themes and design unique cards by selecting your own colors and backgrounds!

0. CRT.

https://pixel-profile.vercel.app/api/github-stats?username=<username>&theme=crt

1. Journey without pixelated avatar.

https://pixel-profile.vercel.app/api/github-stats?username=<username>&theme=journey&pixelate_avatar=false

With dithering.

The dithering=true configuration is a standalone setting that can be applied to any theme.

https://pixel-profile.vercel.app/api/github-stats?username=<username>&theme=journey&dithering=true&hide=avatar

2. Road trip without pixelated avatar.

https://pixel-profile.vercel.app/api/github-stats?username=<username>&theme=road_trip&pixelate_avatar=false

3. Fuji without pixelated avatar.

https://pixel-profile.vercel.app/api/github-stats?username=<username>&theme=fuji&pixelate_avatar=false

4. Rainbow without pixelated avatar.

https://pixel-profile.vercel.app/api/github-stats?username=<username>&theme=rainbow&pixelate_avatar=false

5. Monica.

https://pixel-profile.vercel.app/api/github-stats?username=<username>&theme=monica

6. Summer.

https://pixel-profile.vercel.app/api/github-stats?username=<username>&theme=summer

7. Lax.

https://pixel-profile.vercel.app/api/github-stats?username=<username>&theme=lax

Github Stats Card Options

Name	Description	Default value
background	Set background color/image. Supports a subset of CSS background property values	#434343
color	Set text color to any valid CSS color value	white
hide	Hide specific stats or elements by passing a comma-separated list. Valid keys: 'avatar', 'commits', 'contributions', 'issues', 'prs', 'rank', 'stars'
include_all_commits	Count all commits	false
pixelate_avatar	Apply pixelation to avatar	true
screen_effect	Enable curved screen effect	false
username	GitHub username	''
theme	Check out the built-in themes below	''
dithering	Render the image using a 256-color palette with dithering	false

Hiding individual stats

You can pass a query parameter &hide= to hide any specific stats with comma-separated values.

Options: &hide=avatar,commits,contributions,issues,prs,rank,stars

<!--Replace <username> with your own GitHub username.-->
https://pixel-profile.vercel.app/api/github-stats?username=<username>&hide=rank

GitHub Actions

Pre-generate your stats cards using GitHub Actions for faster loading and reliable availability.

Basic Usage

Create a workflow file (e.g., .github/workflows/pixel-profile.yml):

name: generate-and-upload-card

on:
  # run automatically every 24 hours
  schedule:
    - cron: "0 */24 * * *"

  # allows to manually run the job at any time
  workflow_dispatch:

  # run on every push on the master branch
  push:
    branches:
      - master

jobs:
  generate:
    permissions:
      contents: write
    runs-on: ubuntu-latest
    timeout-minutes: 5

    steps:
      - name: generate github stats card
        uses: LuciNyan/pixel-profile/action@main
        with:
          outputs: |
            dist/github-stats?username=<username>&screen_effect=false&theme=fuji&dithering=true&hide=avatar
            dist/github-stats-dark?username=<username>&theme=crt
          crt_outputs: |
            dist/github-stats-crt?username=<username>&include_all_commits=true
            
      - name: push cards to the output branch
        uses: crazy-max/ghaction-github-pages@v3.1.0
        with:
          target_branch: output
          build_dir: dist
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Action Inputs

Input	Description	Required
github_token	GitHub token for fetching contribution data	No
outputs	List of standard stats files to generate	No
crt_outputs	List of CRT-style stats files to generate	No

Output File Options

For outputs (standard stats card):

• All options from the Github Stats Card Options table
• Format: filename?option1=value1&option2=value2

For crt_outputs (CRT stats card):

• username: GitHub username
• include_all_commits: Count all commits (default: false)
• exclude_repo: Comma-separated list of repos to exclude
• Format: filename?username=<username>&include_all_commits=true

Deploy on your own

The GitHub API has a rate limit of 5k requests per hour, so the public https://pixel-profile.vercel.app/api could potentially hit that limit. By self-hosting, you eliminate this concern.

Deploy on Vercel (Recommended)

1. Creating a Personal Access Token

To use this tool to retrieve user statistics, you'll need to generate a Personal Access Token (PAT) with the proper scopes.

Click here to create a new PAT.

Under "Select scopes" check the box for "repo" and "user" like in the image below:

Copy the generated PAT for use in the config file or as an environment variable.

2. Deploy to Vercel

3. Using the PAT with Vercel

Once you have generated a Personal Access Token (PAT) from your GitHub account, you'll need to add it to your Vercel project configuration in order to authenticate API requests.

To add the PAT to Vercel:

Other platforms or self-hosted

In addition to Vercel, you can also deploy to other PaaS platforms (e.g. zeabur.com, heroku.com, fly.io) or hosted on your own server!

Deploy on Zeabur

First you need to have a zeabur account.

Fork this repository and log in to Zeabur.

"Create a Project (or select an existing one)" - "Add Service" - "Git" - "Select the forked pixel-profile repository".

Don't forget to add your "Personal Access Token (PAT) " in "Variable".

Finally, go to "Networking" and generate a domain (or bind your own).

Running on docker

Warning

When hosting on Docker, caching is not available, which can quickly cause the API rate limits to be exceeded. It is recommended to use Nginx or a CDN as a proxy to provide caching functionality and optimize performance.

# Clone repository
git clone https://github.com/LuciNyan/pixel-profile.git

# Go to the directory to build the Docker image
cd pixel-profile
docker build -t pixel-profile .

# Create and start the container
docker run -d \
  --name pixel-profile \
  -p 3000:3000 \
  -e PAT_1=ghp_xxxxxx \ # Please change it to your "Personal Access Token (PAT) "
  -e PORT=3000 \
  --restart always \
  pixel-profile

# The service has successfully started on port 3000!

Contributing

The layout in this project is built entirely with JSX, making development nearly identical to a normal React project. Anyone can easily create new cards with minimal effort. If you have any ideas, feel free to contribute!

Running Locally

Follow these 4 easy steps to get pixel-profile running on your local machine:

1. Install dependencies

pnpm install

2. Generate a Personal Access Token (PAT)

Refer to the "Creating a Personal Access Token" section above.

3. Create a .env file

Use .env.example as a guide to set your environment variables.

PAT_1=xxxxxxx

4. Run! 🚀

pnpm start

Roadmap

• GitHub stats card
• CRT-style stats card

Author

• LuciNyan

 

This Pixel Profile project would not have been possible without these amazing projects:

Github Readme Stats: One of the best tools out there for generating awesome Github stats cards.

resvg-js: A high-performance SVG renderer and toolkit.

Satori: An enlightened library to convert HTML and CSS to SVG.

Jubilee A truly unmatched pixel artist! ❤️