pixel-profile: a pixel art stats card for your GitHub README, rendered as an image

The card is an image URL you paste into a README

The whole idea fits in one line. You can easily generate a GitHub stats card with default styling using a link like this:

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

The result is an image, which means you embed it in a README with markdown or HTML and GitHub renders it like any other asset. The deployment is at pixel-profile.vercel.app, and the project is MIT licensed with the version at 1.3.0. The repository topics explain the stack, with satori, jsx, serverless, vercel, readme-generator, and readme-stats among them, which is the whole pipeline in one list. Satori is what makes this shape of project possible, because it renders JSX to an SVG or PNG without a browser, and a serverless function that returns an image is a good fit for a public API that any number of READMEs can point at.

Light and dark variants use a picture element with two sources

The card is customised through query parameters, and the recommended setup for a README is a `<picture>` element with a media query for the user's colour scheme, so the card matches the theme GitHub is rendering in. The README gives this configuration:

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

The `decoding` and `loading` attributes are the small performance touches, with async decoding and lazy loading, and the `alt` text is there for accessibility. The `srcset` on each source points at a different theme, so the dark variant can enable the screen effect while the light one does not. The author points at their own profile repository as a ready-made example configuration, which is the fastest way to see a working setup.

Themes are query parameters, and every theme can be overridden

There is a long list of prebuilt themes, each selected with a `theme` parameter. The README shows `crt`, `journey`, `road_trip`, `fuji`, `rainbow`, `monica`, `summer`, and `lax`, each with its own example link, and the numbering in the documentation is even preserved from an earlier version of the list. Underneath the presets, the cards are fully customisable by passing background and color props, and the README invites you to ditch the premade themes and design unique cards by selecting your own colors and backgrounds. Several themes also accept a `pixelate_avatar=false` parameter to turn off the pixelation of the profile picture, and there is a standalone `dithering=true` setting that can be applied to any theme.

The options table is the actual contract

The README ends the visible section with a table of GitHub stats card options, and it is the most useful part of the documentation for anyone embedding a card. `background` sets the background color or image and supports a subset of CSS background property values, defaulting to `#434343`. `color` sets the text color to any valid CSS color value, defaulting to `white`. `hide` takes a comma-separated list of elements to remove, with the valid keys being avatar, commits, contributions, issues, prs, rank, and stars. `include_all_commits` counts all commits and defaults to `false`. `pixelate_avatar` applies pixelation to the avatar and defaults to `true`. And `screen_effect` enables the curved screen effect, defaulting to `false`. The default of `include_all_commits` being false is the one that surprises people, since it means the commit count is filtered to the current year unless you ask otherwise.

A CRT theme and a GitHub Action for people on slow connections

The most recent additions in the README are the CRT stats card and the GitHub Actions integration. The CRT card is described as a retro style card with an authentic CRT monitor frame with a curved screen effect, scanlines, RGB shift, and phosphor glow effects, and it is available through GitHub Actions with a `crt_outputs` parameter. The Actions integration exists so you can pre-generate your stats cards, and the README gives two reasons: instant visibility even in poor network conditions, and faster loading times for your GitHub profile. That is a sensible design decision for a project whose whole purpose is an image in a README, because a cold serverless function plus a GitHub API round trip is exactly the kind of thing that makes a README feel slow. The `action/` directory in the repository holds the workflow, and the README points at LuciNyan's own profile for a working example.

The server is a Hono app on Node with a PAT behind it

The repository layout shows a monorepo with a `packages/` directory, an `api/` directory for the serverless functions, an `action/` directory for the workflow, and a `Dockerfile`. The `package.json` names the project `github-pixel-profile` and is an ES module package with scripts for `vercel dev` for local API development, a Turbo-driven dev command for the pixel-profile package, Vitest for tests, and `bumpp` plus `pnpm publish` for releases. The Dockerfile builds on `node:20-alpine`, installs pnpm globally, runs a frozen lockfile install, builds the workspace, and deploys only the `pixel-profile-server` package into a production image, along with the font files. It runs as a non-root `hono` user with `NODE_ENV=production`, exposes a `PORT` that defaults to 3000, and starts the server with `node --experimental-modules`.

Where this project is the wrong choice

Two limitations stand out, and both come from the same decision: the output is an image. The first is that the numbers in your README go stale. The card is generated when the image is requested, or when the Action regenerates it, and either way it is a snapshot. A project that wants live commit counts in its README needs a different approach, and one that wants a dashboard of contribution history needs more than a single card, since the `hide` parameter only removes elements from a fixed layout. The second is the dependency on a hosted service and a GitHub token, with the `.env.example` file in the repository containing a single `PAT_1=` entry, which is the personal access token the server uses to read your GitHub data. For a personal README that is fine. For an organisation that cannot depend on a third party endpoint or that does not want to hand a token to one, the answer is to fork the project and run the container yourself, which the Dockerfile supports but the README does not document in detail.

Editorial conclusion

pixel-profile fits a developer who wants a stats card in a README and is willing to link an external image endpoint, or who wants to pre-generate the card with a GitHub Action so it renders fast on a slow connection. It is the wrong tool if you need the numbers to be live on every page load, since the card is an image fetched at view time, and it is the wrong tool if you want a full dashboard rather than one card. Before you adopt it, read the options table in the README, because the `hide` and `background` parameters decide what the card shows, and note that the card depends on a hosted service and a GitHub token, so a self-hosted fork needs its own.

Frequently asked questions

Official sources

1. License: MIT
2. LuciNyan/pixel-profile on GitHub
3. Project website
4. README
5. Releases